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