[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation about the completion framework
From: |
Daniele Nicolodi |
Subject: |
Re: Documentation about the completion framework |
Date: |
Mon, 21 Jan 2019 15:21:15 -0700 |
User-agent: |
Mozilla/5.0 (Macintosh; Intel Mac OS X 10.13; rv:60.0) Gecko/20100101 Thunderbird/60.4.0 |
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