From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.ciao.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: Documentation about the completion framework Date: Mon, 21 Jan 2019 16:17:11 -0500 Message-ID: References: <62c8a43a-16f4-cd86-da24-df3dcbe68537@grinta.net> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.org; posting-host="ciao.gmane.org:195.159.176.228"; logging-data="155407"; mail-complaints-to="usenet@ciao.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jan 21 22:17:46 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1glgwt-000eII-9C for ged-emacs-devel@m.gmane.org; Mon, 21 Jan 2019 22:17:39 +0100 Original-Received: from localhost ([127.0.0.1]:60748 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1glgws-0008TH-95 for ged-emacs-devel@m.gmane.org; Mon, 21 Jan 2019 16:17:38 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:42670) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1glgwg-0008Sw-7n for emacs-devel@gnu.org; Mon, 21 Jan 2019 16:17:26 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1glgwf-0007LY-7d for emacs-devel@gnu.org; Mon, 21 Jan 2019 16:17:26 -0500 Original-Received: from [195.159.176.228] (port=48316 helo=ciao.gmane.org) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1glgwf-0007Kk-06 for emacs-devel@gnu.org; Mon, 21 Jan 2019 16:17:25 -0500 Original-Received: from list by ciao.gmane.org with local (Exim 4.89) (envelope-from ) id 1glgwY-000e0P-OB for emacs-devel@gnu.org; Mon, 21 Jan 2019 22:17:18 +0100 X-Injected-Via-Gmane: http://gmane.org/ Cancel-Lock: sha1:uAlljq4aT7PUgYvmpHP+PGBalAI= X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 195.159.176.228 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:232582 Archived-At: > 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