Documentation about the completion framework

Documentation about the completion framework

[Daniele Nicolodi]

Hello,

I'm implementing completion-at-point for an emacs mode.

Unfortunately docstring of the relevant elisp functions are not always
detailed and in some cases not complete. I would also really appreciate
some documentation on how the framework can be used and how is it
supposed to be used, even better if there would be some hints on how to
keep it efficient.

Does such documentation exist somewhere? Does anyone have any resource
to recommend?

One specific question I have: in some circumstances completion-at-point
enters a mode in which it is called for each keystroke (I think this is
completion-in-region-mode). How does this happen and why? I would like
to avoid that my function to collect completion targets get called on
each keystroke. Is there a way to do that?

Another question: what is the most efficient way to collect completion
targets in the current buffer? Is there an alternative from doing it at
ache invocation of the completion-at-point hook?

Thank you!

Cheers,
Dan

Re: Documentation about the completion framework

[Eric Abrahamsen]

Daniele Nicolodi <daniele@grinta.net> writes:

> Hello,
>
> I'm implementing completion-at-point for an emacs mode.
>
> Unfortunately docstring of the relevant elisp functions are not always
> detailed and in some cases not complete. I would also really appreciate
> some documentation on how the framework can be used and how is it
> supposed to be used, even better if there would be some hints on how to
> keep it efficient.
>
> Does such documentation exist somewhere? Does anyone have any resource
> to recommend?

I'm partway through a blog post about exploring the internals of
completion, but it won't be done for a little bit yet. I will try to
remember to send you a link when it's done. :)

Eric

Re: Documentation about the completion framework

[Stefan Monnier]

> Unfortunately docstring of the relevant elisp functions are not always
> detailed and in some cases not complete. I would also really appreciate
> some documentation on how the framework can be used and how is it
> supposed to be used, even better if there would be some hints on how to
> keep it efficient.
>
> Does such documentation exist somewhere? Does anyone have any resource
> to recommend?

It's mostly available in docstrings.
For example, C-h o completion-at-point-functions says:

    [...]
    NOTE: These functions should be cheap to run since they’re sometimes
    run from ‘post-command-hook’; and they should ideally only choose
    which kind of completion table to use, and not pre-filter it based
    on the current text between START and END (e.g., they should not
    obey ‘completion-styles’).

> One specific question I have: in some circumstances completion-at-point
> enters a mode in which it is called for each keystroke (I think this is
> completion-in-region-mode). How does this happen and why?  I would like
> to avoid that my function to collect completion targets get called on
> each keystroke. Is there a way to do that?

Yes: don't collect candidates when that function is called.
Instead, the function should return a completion table which will
compute the candidates only if it's called.  E.g.:

    (defun my-completion-at-point-function ()
      (when (relevant)
        (let (candidates
              (candidates-computed nil)
              (start ...)
              (end ...)
              (completion-table
               (lambda (string pred action)
                 (unless candidates-computed
                   (setq candidates-computed t)
                   (setq candidates (my-collect-candidates)))
                 (complete-with-action action candidates string pred))))
          (list start end completion-table))))

tho you probably want to cache your completion candidates elsewhere
(exactly where to cache them depends on when they need to be
recomputed, so often it's best to cache them in a global variable and
flush them from other places in the code).


        Stefan

Re: Documentation about the completion framework

[Daniele Nicolodi]

Hi Stefan,

thank you for the detailed answer.

On 21/01/2019 14:17, Stefan Monnier wrote:
>> Unfortunately docstring of the relevant elisp functions are not always
>> detailed and in some cases not complete. I would also really appreciate
>> some documentation on how the framework can be used and how is it
>> supposed to be used, even better if there would be some hints on how to
>> keep it efficient.
>>
>> Does such documentation exist somewhere? Does anyone have any resource
>> to recommend?
> 
> It's mostly available in docstrings.

Indeed, but, for example, I was unable to find how a completion table
should be defined or what it should return. Maybe missed it, but I would
have expected this to be linked from the completion-at-point-functions
docstring. Also, I was unable to find what is the role of the start and
end markers. In the specific, what's the purpose of specifying an end
that is past (point) ?

> For example, C-h o completion-at-point-functions says:
> 
>     [...]
>     NOTE: These functions should be cheap to run since they’re sometimes
>     run from ‘post-command-hook’; and they should ideally only choose
>     which kind of completion table to use, and not pre-filter it based
>     on the current text between START and END (e.g., they should not
>     obey ‘completion-styles’).
> 
>> One specific question I have: in some circumstances completion-at-point
>> enters a mode in which it is called for each keystroke (I think this is
>> completion-in-region-mode). How does this happen and why?  I would like
>> to avoid that my function to collect completion targets get called on
>> each keystroke. Is there a way to do that?
> 
> Yes: don't collect candidates when that function is called.
> Instead, the function should return a completion table which will
> compute the candidates only if it's called.

How is a completion table defined? what are the string, pred, action
arguments passed to it? What should it return?

>  E.g.:
> 
>     (defun my-completion-at-point-function ()
>       (when (relevant)
>         (let (candidates
>               (candidates-computed nil)
>               (start ...)
>               (end ...)
>               (completion-table
>                (lambda (string pred action)
>                  (unless candidates-computed
>                    (setq candidates-computed t)
>                    (setq candidates (my-collect-candidates)))
>                  (complete-with-action action candidates string pred))))
>           (list start end completion-table))))
> 
> tho you probably want to cache your completion candidates elsewhere
> (exactly where to cache them depends on when they need to be
> recomputed, so often it's best to cache them in a global variable and
> flush them from other places in the code).

This is good advice, but a bit too high level for me to be able to
translate it into code. Where should I look for examples of this sort of
caching?

Thank you!

Cheers,
Dan

Re: Documentation about the completion framework

[Daniele Nicolodi]

On 21/01/2019 12:49, Eric Abrahamsen wrote:
> I'm partway through a blog post about exploring the internals of
> completion, but it won't be done for a little bit yet. I will try to
> remember to send you a link when it's done. :)
Thanks Eric. However, if your blog is indexed on Planet Emacsen I will
see your post in my RSS feed.

Cheers,
Dan

Re: Documentation about the completion framework

[Eric Abrahamsen]

Daniele Nicolodi <daniele@grinta.net> writes:

> On 21/01/2019 12:49, Eric Abrahamsen wrote:
>> I'm partway through a blog post about exploring the internals of
>> completion, but it won't be done for a little bit yet. I will try to
>> remember to send you a link when it's done. :)
> Thanks Eric. However, if your blog is indexed on Planet Emacsen I will
> see your post in my RSS feed.

Ah, good point. I was going to repost to emacs.tangents, but perhaps
Planet Emacsen is better.

RE: Documentation about the completion framework

[Drew Adams]

> I'm partway through a blog post about exploring the internals of
> completion, but it won't be done for a little bit yet. I will try to
> remember to send you a link when it's done. :)

Please consider adding the info (perhaps in a different form)
to the Emacs doc.

Re: Documentation about the completion framework

[Daniele Nicolodi]

Hi Stefan,

On 21/01/2019 14:17, Stefan Monnier wrote:
> Yes: don't collect candidates when that function is called.
> Instead, the function should return a completion table which will
> compute the candidates only if it's called.  E.g.:
> 
>     (defun my-completion-at-point-function ()
>       (when (relevant)
>         (let (candidates
>               (candidates-computed nil)
>               (start ...)
>               (end ...)
>               (completion-table
>                (lambda (string pred action)
>                  (unless candidates-computed
>                    (setq candidates-computed t)
>                    (setq candidates (my-collect-candidates)))
>                  (complete-with-action action candidates string pred))))
>           (list start end completion-table))))

Trying to understand this code: how is this different from computing
candidates directly in my-completion-at-point-function and passing it down?

I must be missing something.

Thank you!

Cheers,
Dan

Re: Documentation about the completion framework

[Stefan Monnier]

> Trying to understand this code: how is this different from computing
> candidates directly in my-completion-at-point-function and passing it down?

The completion function is not always called.
The completion-in-region-mode for example just calls
completion-at-point-function after each command (without looking up the
completion-table) just to see if we're still within the same field.


        Stefan

Re: Documentation about the completion framework

[Daniele Nicolodi]

On 21/01/2019 20:37, Stefan Monnier wrote:
>> Trying to understand this code: how is this different from computing
>> candidates directly in my-completion-at-point-function and passing it down?
> 
> The completion function is not always called.
> The completion-in-region-mode for example just calls
> completion-at-point-function after each command (without looking up the
> completion-table) just to see if we're still within the same field.

I see. Unfortunately I didn't find any documentation of this mechanism.
Did I overlook it, or should I think about submitting a patch improving
the docstrings?

Thansk!

Cheers,
Dan

Re: Documentation about the completion framework

[Stefan Monnier]

> I see. Unfortunately I didn't find any documentation of this mechanism.

I'm not sure what that would look like.  To me it's just an obvious
consequence of the difference between returning a list and returning
a function that returns a list.

> Did I overlook it, or should I think about submitting a patch improving
> the docstrings?

If you can provide some sample wording that would have helped you,
that'd be great.


        Stefan

Re: Documentation about the completion framework

[Eric Abrahamsen]

Drew Adams <drew.adams@oracle.com> writes:

>> I'm partway through a blog post about exploring the internals of
>> completion, but it won't be done for a little bit yet. I will try to
>> remember to send you a link when it's done. :)
>
> Please consider adding the info (perhaps in a different form)
> to the Emacs doc.

I'll see what I can do! It would have to be in quite a different form,
though.

RE: Documentation about the completion framework

[Drew Adams]

 
> >> I'm partway through a blog post about exploring the internals of
> >> completion, but it won't be done for a little bit yet. I will try to
> >> remember to send you a link when it's done. :)
> >
> > Please consider adding the info (perhaps in a different form)
> > to the Emacs doc.
> 
> I'll see what I can do!

Great. Thanks.

> It would have to be in quite a different form, though.

Yes.