From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Toby Cubitt Newsgroups: gmane.emacs.devel Subject: Re: Emacs completion matches selection UI Date: Tue, 7 Jan 2014 03:57:40 +0000 Message-ID: <20140107035740.GA3622@c3po> References: <871u0kfzpe.fsf@flea.lifelogs.com> Reply-To: Toby Cubitt NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1389067070 12990 80.91.229.3 (7 Jan 2014 03:57:50 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 7 Jan 2014 03:57:50 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jan 07 04:57:58 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1W0Nng-0004vr-O0 for ged-emacs-devel@m.gmane.org; Tue, 07 Jan 2014 04:57:56 +0100 Original-Received: from localhost ([::1]:38648 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W0Nng-00082o-FB for ged-emacs-devel@m.gmane.org; Mon, 06 Jan 2014 22:57:56 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53336) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W0NnZ-00081l-Ul for emacs-devel@gnu.org; Mon, 06 Jan 2014 22:57:54 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1W0NnV-0004Q6-IL for emacs-devel@gnu.org; Mon, 06 Jan 2014 22:57:49 -0500 Original-Received: from sanddollar.geekisp.com ([216.168.135.167]:47372) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1W0NnV-0004Q2-Dh for emacs-devel@gnu.org; Mon, 06 Jan 2014 22:57:45 -0500 Original-Received: (qmail 20736 invoked by uid 1003); 7 Jan 2014 03:57:44 -0000 Original-Received: from localhost (localhost.geekisp.com [127.0.0.1]) by localhost.geekisp.com (tmda-ofmipd) with ESMTP; Mon, 06 Jan 2014 22:57:42 -0500 Content-Disposition: inline In-Reply-To: <871u0kfzpe.fsf@flea.lifelogs.com> X-PGP-Key: http://www.dr-qubit.org/gpg-toby-pub.asc User-Agent: Mutt/1.5.22 (2013-10-16) X-Delivery-Agent: TMDA/1.1.11 (Ladyburn) X-Primary-Address: toby@dr-qubit.org X-detected-operating-system: by eggs.gnu.org: OpenBSD 4.x-5.x [fuzzy] X-Received-From: 216.168.135.167 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 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-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:167566 Archived-At: On Mon, Jan 06, 2014 at 06:38:37PM -0500, Ted Zlatanov wrote: > On Sat, 4 Jan 2014 00:48:53 +0000 Toby Cubitt wrote: > TC> Since it's the completion UI that will have to interpret and make use of > TC> the extras, one place to start is to think about what additional features > TC> the UI might want to provide, beyond selecting from a list of possible > TC> completions. > > TC> Luckily, we have many existing completion frameworks to draw on for > TC> inspiration. At the moment, location data and various forms of > TC> documentation (e.g. type information in code completion, docstrings, > TC> etc.) are the only ones that spring to mind. > > Add: feedback from frontend to backend (Predictive use case we > mentioned, needs API support through callbacks). Pluggable completion > frontends (not in the API) Or rather, requires a separate API. Both Completion-UI and Company already have APIs for this (though the discussion's mostly focused on the completion UI API so far). > Dynamic limiting of completion candidates as characters are typed (not > in the API). All Completion-UI widgets already implement this(*), and the UI widget API ensures that any third-part widgets will also automatically support this too. (*) The mouse-driven toolkit menus break it by stealing the keyboard focus, but that's a technicality. > The backend should be able to provide hints about the data. For > instance, "this is a list of ELisp symbols" could look different from > "this is a list of installable packages." Also icons are important IMO, > based on the hints or the candidates. > > TC> The keyword arguments to `completion-ui-register-source' are one starting > TC> point for seeing what additional properties might be needed, as are the > TC> corresponding APIs in Company, auto-complete, etc. > > Can you or Dmitry compile a list? Here are the important ones (copied from the docstring): :activate FUNCTION The function called to activate the user-interface. :deactivate FUNCTION The function called to deactivate the user-interface. :update FUNCTION (optional) A function to call to update the user-interface after a change to the current completion. If it is not specified, the interface is updated by calling the :deactivate function, updating the completion, then calling the :activate function. :auto-show FUNCTION (optional) A function to call to activate a this user-interface as an auto-show interface. The auto-show interface is chosen by setting the `completion-auto-show' customization option. Only one auto-show interface can be displayed at any one time. :auto-show-helper FUNCTION (optional) A function to call whenever any auto-show interface is activated for a completion. In Completion-UI, all of these functions are passed a single argument: an overlay which demarcates where in the buffer the completion is taking place, and whose properties contain relevant data about the completion process. I rather like passing the data in overlay properties, because it keeps the data together with the location in the buffer where things are happening. But one could pass the data through buffer-local variables if preferred. The following overlay properties store the standard completion-related data: prefix The prefix or string being completed. prefix-length Length of the prefix or string currently being completed. (For convenience, to avoid having to repeatedly call (length (overlay-get completion-overlay prefix)) completions A list of completion candidates. completion-num Index of currently selected completion candidate, or nil if completions list is empty. completion-overlay Always t for a completion overlay. completion-source The completion source ("backend") used to obtain the completion candidates. completion-prefix-function Function that was used to find the prefix or string to complete. non-prefix-completion Nil if doing standard prefix completion, non-nil if doing something other than prefix completion (such as pattern matching). prefix-replaced Non-nil if buffer string being completed (stored in prefix overlay property) has been replaced with new text in the buffer. (Only relevant when doing non-prefix completion.) common-substring If set, an overlay marking the longest common substring of the completion text currently inserted in the buffer, if any. keymap Keymap active within the completion overlay. Usually derived from `completion-overlay-map' or `auto-completion-overlay-map'. auto-show Name of auto-show interface (symbol) currently being displayed, or nil if no auto-show interface is active. > TC> Also, if we want to allow users to optionally customize the completion UI > TC> per-backend (a la Completion-UI), there has to be some way of identifying > TC> backends in Customize. This seems necessary to me if the new API is to > TC> become the standard way of implementing a completion UI in Emacs. Think > TC> minibuffer completion, versus filename completion, versus predictive > TC> completion, versus elisp code completion etc, all of which might want to > TC> use slightly different UI options. Again, it might be enough to support a > TC> :name property (or some such) in the `completion-at-point-functions' > TC> PROPS plist. > > The frontend UI should depend (in my mind) on three things: 1) the > invocation context as you showed; 2) the backend-provided hints about > the data as a whole; and 3) the backend-provided hints about each > completion candidate individually. Does that make sense? Yes, it makes sense. I suspect most of the time the UI will only need to depend on which backend is being used (and often not even on that). I can't think of any situations in which it will need to depend on the completions returned by the backend. But maybe there are some cases. > Some frontends may ignore some or all of those things, but I think > those are the principal axis. I don't know how those three things will > be passed to the frontend though, and when. Everything I've ever wanted to do with Completion-UI is covered by allowing various configuration variables to take backend-specific values. I've never needed the UI to depend on the return value of the backend. Maybe Dmitry has examples from Company? > >> - the frontend choices made by the user should be able to feed back into > >> the data backend (the "predictive" use case) > > TC> A few optional hooks/call-backs would very likely be sufficient. Again, > TC> the `completion-at-point-functions' PROPS plist would be the obvious > TC> place to specify them. > > OK, this is your use case :) I'm just bowing to the inevitable outcome that we'll end up extending c-a-p-f rather than designing a new API for the completion sources. > >> - we have enough interest and support in this work that it's worth > >> undertaking in earnest after the code freeze. The discussion should > >> remain on emacs-devel (based on the wide interest so far). > ... > TC> (Note that I'm unlikely to have time to code anything myself until > TC> March/April, although the feature freeze will likely delay things until > TC> about then anyway. I'm happy to help in a more limited way before then, > TC> as time allows.) > > Cool. We seem to be moving towards a specific API, refining the current > Emacs internals, which is good. I'd be OK with it looking like > completion-ui as long as it was at least somewhat backwards compatible > and could support the packages we mentioned. By "looking like completion-UI", do you mean the API or what it actually looks like? I think the completion source API is likely to look exactly like completion-at-point-functions, because that's already in Emacs and I'm running out of compelling arguments for changing it, even though I don't love it. But Dmitry may hold out longer than me on this ;-) > To me, the clearest indication of a good approach would be if both the > Emacs core and external packages were able to lose lines of code. I'm hoping the Predictive package can lose 9 entire elisp files, for a start (all the Completion-UI files ;-) Toby -- Dr T. S. Cubitt Royal Society University Research Fellow and Fellow of Churchill College, Cambridge Centre for Quantum Information DAMTP, University of Cambridge email: tsc25@cantab.net web: www.dr-qubit.org