From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.ciao.gmane.org!not-for-mail From: Daniele Nicolodi Newsgroups: gmane.emacs.devel Subject: Re: Documentation about the completion framework Date: Mon, 21 Jan 2019 15:21:15 -0700 Message-ID: <2411a612-1468-3997-8fc7-e195d5c53a79@grinta.net> References: <62c8a43a-16f4-cd86-da24-df3dcbe68537@grinta.net> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.org; posting-host="ciao.gmane.org:195.159.176.228"; logging-data="171123"; mail-complaints-to="usenet@ciao.gmane.org" User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.13; rv:60.0) Gecko/20100101 Thunderbird/60.4.0 To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jan 21 23:33:02 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 1gli7p-000iOk-9t for ged-emacs-devel@m.gmane.org; Mon, 21 Jan 2019 23:33:01 +0100 Original-Received: from localhost ([127.0.0.1]:35181 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gli7o-0003g7-9U for ged-emacs-devel@m.gmane.org; Mon, 21 Jan 2019 17:33:00 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:36501) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gli7Q-0003Ua-1F for emacs-devel@gnu.org; Mon, 21 Jan 2019 17:32:37 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1glhwc-0000CT-F3 for emacs-devel@gnu.org; Mon, 21 Jan 2019 17:21:28 -0500 Original-Received: from zed.grinta.net ([109.74.203.128]:51102) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1glhwW-00008Q-Rx for emacs-devel@gnu.org; Mon, 21 Jan 2019 17:21:23 -0500 Original-Received: from black.hsd1.co.comcast.net (c-98-245-163-4.hsd1.co.comcast.net [98.245.163.4]) (Authenticated sender: daniele) by zed.grinta.net (Postfix) with ESMTPSA id CCAE1E3D0D for ; Mon, 21 Jan 2019 22:21:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=grinta.net; s=mail; t=1548109279; bh=SaXfRMMNC+GrN5F1NDYsmi9uwjS0sMGQKk8A/ywmzdk=; h=Subject:To:References:From:Date:In-Reply-To:From; b=oOXJxlzNYLC8Dra82tNlVCFzZr03D5ov7MwlDAuCOhjoVwpVjPZ+HQuEuLD9P6RHb OErrbuM8waW2DMhB3MS39761ERrMoXaT/03BuUqs0A+FjeRlc5Ad6uxy7idjqJXu7/ 8lzp7IjcYwM6NpU/KeMGuE40IyLWqK0xEH0rpSAQ= Openpgp: preference=signencrypt In-Reply-To: Content-Language: en-US X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 109.74.203.128 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:232586 Archived-At: 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 appreciat= e >> 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 t= o >> keep it efficient. >> >> Does such documentation exist somewhere? Does anyone have any resource >> to recommend? >=20 > 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: >=20 > [...] > NOTE: These functions should be cheap to run since they=E2=80=99re = sometimes > run from =E2=80=98post-command-hook=E2=80=99; and they should ideal= ly 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 =E2=80=98completion-styles=E2=80=99). >=20 >> One specific question I have: in some circumstances completion-at-poin= t >> enters a mode in which it is called for each keystroke (I think this i= s >> completion-in-region-mode). How does this happen and why? I would lik= e >> to avoid that my function to collect completion targets get called on >> each keystroke. Is there a way to do that? >=20 > 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.: >=20 > (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)))) >=20 > 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