Stefan Kangas <stefankangas@HIDDEN>
to control <at> debbugs.gnu.org.
Full text available.
Received: (at 76941) by debbugs.gnu.org; 12 Mar 2025 15:26:01 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Mar 12 11:26:00 2025
Received: from localhost ([127.0.0.1]:51292 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1tsNy4-00055t-IL
for submit <at> debbugs.gnu.org; Wed, 12 Mar 2025 11:26:00 -0400
Received: from eggs.gnu.org ([2001:470:142:3::10]:38720)
by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.84_2) (envelope-from <eliz@HIDDEN>) id 1tsNy1-00055e-Cg
for 76941 <at> debbugs.gnu.org; Wed, 12 Mar 2025 11:25:58 -0400
Received: from fencepost.gnu.org ([2001:470:142:3::e])
by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <eliz@HIDDEN>)
id 1tsNxv-0001FA-40; Wed, 12 Mar 2025 11:25:51 -0400
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org;
s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date:
mime-version; bh=Yrw8L/WbrGfZWOKU1m2wDEY+8pI7crkWsAAxRrK9QFs=; b=oj8fEbiJ2Wce
rdzrO+audXORDrdCrDtpYaQtDnCX2DOV5wqyR2RPY5ql1Ol9o2K6nvC7Dey9wHBD7sPHbz0hf8TfA
6tvjDJUHnsLUxO8CMlY2blr2aajZeGD5LR4G0UedkCf8g2EdtVSVbta1j1+kc4pumCI2qnbnWT76d
9n/Wjx1alFw9iCiKPoxBwBzQAF9T3rYMQwpLqSu2c6p6XBsDcDDaKkXH+aZBTe6M2yQXWJaxQSThB
orDBSU69Enk/LWppj8WE5vsdSK1VR95GVHo1gucsIAhutcq+YsUTPujvoEf8C8NN+cKX02YT+DWd9
IC0tt+bTeH8en8sTV+9TgA==;
Date: Wed, 12 Mar 2025 17:25:48 +0200
Message-Id: <86a59q5kzn.fsf@HIDDEN>
From: Eli Zaretskii <eliz@HIDDEN>
To: Eshel Yaron <me@HIDDEN>
In-Reply-To: <m1frjibbg7.fsf@HIDDEN> (message from Eshel Yaron on
Wed, 12 Mar 2025 14:55:20 +0100)
Subject: Re: bug#76941: [PATCH] completion-preview.el: Provide an API.
References: <m1y0xbhgrd.fsf@HIDDEN> <86plinbshg.fsf@HIDDEN>
<m1o6y7hcq9.fsf@HIDDEN> <86cyenbijw.fsf@HIDDEN>
<m1h63zguue.fsf@HIDDEN> <86frji76cu.fsf@HIDDEN>
<m1frjibbg7.fsf@HIDDEN>
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 76941
Cc: 76941 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)
> From: Eshel Yaron <me@HIDDEN>
> Cc: 76941 <at> debbugs.gnu.org
> Date: Wed, 12 Mar 2025 14:55:20 +0100
>
> Eli Zaretskii <eliz@HIDDEN> writes:
>
> >> + Emacs can also @emph{suggest} possible in-buffer completions by means
> >> +of a @dfn{completion preview}. The preview appears after a given
> >> +stretch of buffer text, usually ending at point, and suggest a possible
> >> +completion of that text. Users can interact with the preview to accept
> >> +the completion suggestion or cycle among multiple suggestions. Use the
> >> +following functions to create or dismiss a completion preview:
> >
> > The ELisp manual is written for Lisp programmers, not for Emacs
> > users. So please use "Lisp programs" instead of "users"
>
> We are telling Lisp programmers what their users can do with the
> completion preview, so this is about users, not other programs.
> Does that makes sense?
Yes, But then I'd say something like "Users can then interact with
this preview to ..."
bug-gnu-emacs@HIDDEN:bug#76941; Package emacs.
Full text available.
Received: (at 76941) by debbugs.gnu.org; 12 Mar 2025 13:55:28 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Mar 12 09:55:28 2025
Received: from localhost ([127.0.0.1]:48145 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1tsMYS-0000Lr-4Q
for submit <at> debbugs.gnu.org; Wed, 12 Mar 2025 09:55:28 -0400
Received: from mail.eshelyaron.com ([107.175.124.16]:44314 helo=eshelyaron.com)
by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.84_2) (envelope-from <me@HIDDEN>) id 1tsMYN-0000LP-Vt
for 76941 <at> debbugs.gnu.org; Wed, 12 Mar 2025 09:55:25 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com;
s=mail; t=1741787723;
bh=0bAxH24N+wVPgAP3d1+aF0pHreLFkT/4UUhx1cDiudY=;
h=From:To:Cc:Subject:In-Reply-To:References:Date:From;
b=hPILZAzEjkV3+qG1g94wnHhO12Ljx5JdGoz5/Ad5JWwkPddQmnKYSWwt2Q/Ia7bo7
hGSQGy+89/zXTC8WPzvOLCdMUCAGH7ZB43BOZqF4gvirmUOX5xMiqSgFsg7p/ieHa+
gtOU9XtQ7Yxhj9ltmRjXKJx4qu4qOcxN47Aq6yM5C3z8G9kXLzvWjUJLNgf7fArRQS
YwRcMSoMTQ1ZSyLqQBtPxiIfrPQ48MmD7xbADtDUO/15imGZJxuCW2KHgVTdjhSfUC
T5Fsmp5uhrErxdV71H8lnX2azHN+rvjmWbDFfpWIPnuOnm/sjGHex9zwMJ3/dmb5pq
Z3AoPwJyG9VJQ==
From: Eshel Yaron <me@HIDDEN>
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#76941: [PATCH] completion-preview.el: Provide an API.
In-Reply-To: <86frji76cu.fsf@HIDDEN>
References: <m1y0xbhgrd.fsf@HIDDEN> <86plinbshg.fsf@HIDDEN>
<m1o6y7hcq9.fsf@HIDDEN> <86cyenbijw.fsf@HIDDEN>
<m1h63zguue.fsf@HIDDEN> <86frji76cu.fsf@HIDDEN>
Date: Wed, 12 Mar 2025 14:55:20 +0100
Message-ID: <m1frjibbg7.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Score: 0.0 (/)
X-Debbugs-Envelope-To: 76941
Cc: 76941 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)
Eli Zaretskii <eliz@HIDDEN> writes:
>> From: Eshel Yaron <me@HIDDEN>
>> Cc: 76941 <at> debbugs.gnu.org
>> Date: Tue, 11 Mar 2025 21:45:13 +0100
>>
>> >> > Should this be documented in the ELisp manual?
>> >>
>> >> Maybe, I can definitely add something if you think we should. I wonder
>> >> where to mention it though, perhaps in `(elisp)Completion in Buffers'?
>> >
>> > Yes, there.
>>
>> OK, done in the updated patch below.
>
> Thanks, the addition to the manual is okay, with one nit:
>
>> + Emacs can also @emph{suggest} possible in-buffer completions by means
>> +of a @dfn{completion preview}. The preview appears after a given
>> +stretch of buffer text, usually ending at point, and suggest a possible
>> +completion of that text. Users can interact with the preview to accept
>> +the completion suggestion or cycle among multiple suggestions. Use the
>> +following functions to create or dismiss a completion preview:
>
> The ELisp manual is written for Lisp programmers, not for Emacs
> users. So please use "Lisp programs" instead of "users"
We are telling Lisp programmers what their users can do with the
completion preview, so this is about users, not other programs.
Does that makes sense?
> and "call" instead of "use".
OK, will do.
Anyway, I'll wait with this patch for some more feedback before for now.
Thanks,
Eshel
bug-gnu-emacs@HIDDEN:bug#76941; Package emacs.
Full text available.
Received: (at 76941) by debbugs.gnu.org; 12 Mar 2025 12:59:10 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Mar 12 08:59:10 2025
Received: from localhost ([127.0.0.1]:47853 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1tsLfx-0005qP-QC
for submit <at> debbugs.gnu.org; Wed, 12 Mar 2025 08:59:10 -0400
Received: from eggs.gnu.org ([2001:470:142:3::10]:49848)
by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.84_2) (envelope-from <eliz@HIDDEN>) id 1tsLfv-0005qA-NE
for 76941 <at> debbugs.gnu.org; Wed, 12 Mar 2025 08:59:08 -0400
Received: from fencepost.gnu.org ([2001:470:142:3::e])
by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <eliz@HIDDEN>)
id 1tsLfq-0006BY-73; Wed, 12 Mar 2025 08:59:02 -0400
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org;
s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date:
mime-version; bh=VqfQ9KYAELPzS3Qe2cvV0igDuYa1bUAhS7YhsBNelWk=; b=jKU4ay+Ch57U
lsRvZO58GDiOZexc1oPbfnUuflBgg43y6oKkafk5UPBb1R8FSHIyI6NlkX8LX0ol1tpYpMHHts9Nx
gpnvxW/Xw2qsv29whYXBh4bW/ivplCwkvzhgXxXLWYtsdFiTwMSBT+W411ksRpVYsOVD7nBjp1ANv
RwPkycjG33zn7L53ebV1S8Be3DuFGrUiErvEIsbL1s0vIRALsGZwZH1yc0fBmyqLFpPbo7j38TvBU
FsMq++As/hMJiJ7AmxBRIIKrSdlMi3QFlv1RFigpuwaFDC3+SKXkKMQUaeYG1YQAx6j9Otw79OSGT
T8OBnFtRI+ifH4gB+vzuEQ==;
Date: Wed, 12 Mar 2025 14:58:57 +0200
Message-Id: <86frji76cu.fsf@HIDDEN>
From: Eli Zaretskii <eliz@HIDDEN>
To: Eshel Yaron <me@HIDDEN>
In-Reply-To: <m1h63zguue.fsf@HIDDEN> (message from Eshel Yaron on
Tue, 11 Mar 2025 21:45:13 +0100)
Subject: Re: bug#76941: [PATCH] completion-preview.el: Provide an API.
References: <m1y0xbhgrd.fsf@HIDDEN> <86plinbshg.fsf@HIDDEN>
<m1o6y7hcq9.fsf@HIDDEN> <86cyenbijw.fsf@HIDDEN>
<m1h63zguue.fsf@HIDDEN>
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 76941
Cc: 76941 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)
> From: Eshel Yaron <me@HIDDEN>
> Cc: 76941 <at> debbugs.gnu.org
> Date: Tue, 11 Mar 2025 21:45:13 +0100
>
> >> > Should this be documented in the ELisp manual?
> >>
> >> Maybe, I can definitely add something if you think we should. I wonder
> >> where to mention it though, perhaps in `(elisp)Completion in Buffers'?
> >
> > Yes, there.
>
> OK, done in the updated patch below.
Thanks, the addition to the manual is okay, with one nit:
> + Emacs can also @emph{suggest} possible in-buffer completions by means
> +of a @dfn{completion preview}. The preview appears after a given
> +stretch of buffer text, usually ending at point, and suggest a possible
> +completion of that text. Users can interact with the preview to accept
> +the completion suggestion or cycle among multiple suggestions. Use the
> +following functions to create or dismiss a completion preview:
The ELisp manual is written for Lisp programmers, not for Emacs
users. So please use "Lisp programs" instead of "users" and "call"
instead of "use".
bug-gnu-emacs@HIDDEN:bug#76941; Package emacs.
Full text available.
Received: (at 76941) by debbugs.gnu.org; 11 Mar 2025 20:45:20 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Mar 11 16:45:20 2025
Received: from localhost ([127.0.0.1]:46013 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1ts6TX-0005aq-Ja
for submit <at> debbugs.gnu.org; Tue, 11 Mar 2025 16:45:20 -0400
Received: from mail.eshelyaron.com ([107.175.124.16]:50084 helo=eshelyaron.com)
by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.84_2) (envelope-from <me@HIDDEN>) id 1ts6TU-0005QF-Uq
for 76941 <at> debbugs.gnu.org; Tue, 11 Mar 2025 16:45:17 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com;
s=mail; t=1741725916;
bh=g8hOCMBVvjgccyZm+9UpFjYa8T/WcRUZqZXBwklqVSE=;
h=From:To:Cc:Subject:In-Reply-To:References:Date:From;
b=fUGfCc534v7lOVNclqqOcP6jXt4pnLNwX4pKMR/iey1udgxLd7K43fsBlSXbhZq5k
lsBG7EgOy6x4HfdziJ39F7CQG9CIy20rNNnMoRSz2MHWnk76EXpvyWwbeUBubAO5Ig
6k4qbjkZeQeKyu3C4QTZtoy3hoeifwvB0A65rM07GUK1LS/2FYpYirvHtYSLPixc9O
ie3CGsdHkDV/11xLvOIt3TCHAMS8daZ7wC8bqwKvT3/qssGDhWES63Kr5EvqiwHbWt
R9dWC9nYsdhwTez358w8AMWwR5P50sOlVuFWLzfHJ0W1Wc+sIOU1IS6A8V/F0EC7ZP
LUCMh5gJ20rwg==
From: Eshel Yaron <me@HIDDEN>
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#76941: [PATCH] completion-preview.el: Provide an API.
In-Reply-To: <86cyenbijw.fsf@HIDDEN>
References: <m1y0xbhgrd.fsf@HIDDEN> <86plinbshg.fsf@HIDDEN>
<m1o6y7hcq9.fsf@HIDDEN> <86cyenbijw.fsf@HIDDEN>
Date: Tue, 11 Mar 2025 21:45:13 +0100
Message-ID: <m1h63zguue.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13)
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="=-=-="
X-Spam-Score: 0.0 (/)
X-Debbugs-Envelope-To: 76941
Cc: 76941 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)
--=-=-=
Content-Type: text/plain
Eli Zaretskii <eliz@HIDDEN> writes:
>> From: Eshel Yaron <me@HIDDEN>
>> Cc: 76941 <at> debbugs.gnu.org
>> Date: Tue, 11 Mar 2025 15:18:54 +0100
>>
>> Eli Zaretskii <eliz@HIDDEN> writes:
>>
>> >> Date: Tue, 11 Mar 2025 13:51:50 +0100
>> >> From: Eshel Yaron via "Bug reports for GNU Emacs,
>> >> the Swiss army knife of text editors" <bug-gnu-emacs@HIDDEN>
>> >>
>> >> This patch adds an initial API for controlling Completion Preview mode's
>> >> preview overlay from Lisp programs, so other features can reuse the
>> >> completion preview UI.
>> >>
>> >> Any thoughts/comments?
>> >
>> > Should this be documented in the ELisp manual?
>>
>> Maybe, I can definitely add something if you think we should. I wonder
>> where to mention it though, perhaps in `(elisp)Completion in Buffers'?
>
> Yes, there.
OK, done in the updated patch below.
--=-=-=
Content-Type: text/x-patch
Content-Disposition: attachment;
filename=v2-0001-completion-preview.el-Provide-an-API.patch
From 8d7985ab4b0de379d38194256c9e29b456796b37 Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@HIDDEN>
Date: Tue, 11 Mar 2025 11:16:49 +0100
Subject: [PATCH v2] completion-preview.el: Provide an API.
Add new functions for summoning and dismissing the
completion preview programmatically. This lets Lisp code
leverage the completion preview UI for different use cases.
* lisp/completion-preview.el (completion-preview-show): New
function.
(completion-preview-hide): Rename to
'completion-preview--hide', use old name for new public API
function.
(completion-preview--hide): New name, see above.
(completion-preview-active-mode, completion-preview--update)
(completion-preview--show)
(completion-preview--window-selection-change)
(completion-preview--post-command, completion-preview-insert)
(completion-preview-partial-insert)
(completion-preview-complete, completion-preview-mode): Use
new functions to show/hide the preview.
* doc/lispref/minibuf.texi (Completion in Buffers): Document
'completion-preview-show' and 'completion-preview-hide'.
* etc/NEWS: Announce new API functions.
---
doc/lispref/minibuf.texi | 22 +++++++++
etc/NEWS | 5 ++
lisp/completion-preview.el | 98 +++++++++++++++++++++++++-------------
3 files changed, 93 insertions(+), 32 deletions(-)
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 3cc206d2e1d..3dcab636245 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -2237,6 +2237,28 @@ Completion in Buffers
and @var{end}.
@end defun
+ Emacs can also @emph{suggest} possible in-buffer completions by means
+of a @dfn{completion preview}. The preview appears after a given
+stretch of buffer text, usually ending at point, and suggest a possible
+completion of that text. Users can interact with the preview to accept
+the completion suggestion or cycle among multiple suggestions. Use the
+following functions to create or dismiss a completion preview:
+
+@defun completion-preview-show beg end common suffixes &optional base &rest props
+This function shows a completion suggestion for the text between
+@var{beg} and @var{end} in the current buffer. @var{common} is a common
+prefix of all completion suggestions; @var{suffixes} is a list of
+distinct suffixes that, together with @var{common}, make up the
+completion suggestions. The order of @var{suffixes} is the order in
+which the completion preview displays the suggestions, in particular,
+the first element of @var{suffixes} is the one that appears initially.
+@end defun
+
+@defun completion-preview-hide
+This function hides the completion preview, if there is one.
+@end defun
+
+See the commentary in @file{completion-preview.el} for more details.
@node Yes-or-No Queries
@section Yes-or-No Queries
diff --git a/etc/NEWS b/etc/NEWS
index 926d426eaae..6524f9bdd4e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -199,6 +199,11 @@ that your popup interface uses for a more integrated experience.
Note: 'completion-preview-sort-function' was present also in Emacs 30.1,
albeit as a variable, not a user option.
++++
+*** New functions 'completion-preview-show' and 'completion-preview-hide'.
+These new API functions allow Lisp programs to summon and dismiss the
+completion preview at will.
+
** Windows
+++
diff --git a/lisp/completion-preview.el b/lisp/completion-preview.el
index 8f7cba580ba..7d263e3678c 100644
--- a/lisp/completion-preview.el
+++ b/lisp/completion-preview.el
@@ -123,6 +123,10 @@
;; (lambda ()
;; (setq-local completion-preview-overlay-priority 1200)
;; (completion-preview-mode)))
+;;
+;; This library also provides an API that you can use to summon and
+;; dismiss the completion preview programmatically; see the functions
+;; `completion-preview-show' and `completion-preview-hide' for details.
;;; Code:
@@ -336,7 +340,7 @@ completion-preview-require-minimum-symbol-length
(and bounds (<= completion-preview-minimum-symbol-length
(- (cdr bounds) (car bounds)))))))
-(defun completion-preview-hide ()
+(defun completion-preview--hide ()
"Hide the completion preview."
(when completion-preview--overlay
(delete-overlay completion-preview--overlay)
@@ -418,7 +422,7 @@ completion-preview--window-selection-change
(unless (or (eq window (selected-window))
(eq window (minibuffer-selected-window)))
(with-current-buffer (window-buffer window)
- (completion-preview-active-mode -1))))
+ (completion-preview-hide))))
(define-minor-mode completion-preview-active-mode
"Mode for when the completion preview is shown."
@@ -435,7 +439,7 @@ completion-preview-active-mode
completion-preview-active-mode-map))
(remove-hook 'window-selection-change-functions
#'completion-preview--window-selection-change t)
- (completion-preview-hide)))
+ (completion-preview--hide)))
(defvar completion-preview-completion-styles '(basic)
"List of completion styles that Completion Preview mode uses.
@@ -521,28 +525,7 @@ completion-preview--update
(run-hook-wrapped
'completion-at-point-functions
#'completion-preview--capf-wrapper)
- (when-let* ((suffix (car suffixes)))
- (set-text-properties 0 (length suffix)
- (list 'face (if (cdr suffixes)
- 'completion-preview
- 'completion-preview-exact))
- suffix)
- (set-text-properties 0 (length common)
- (list 'face (if (cdr suffixes)
- 'completion-preview-common
- 'completion-preview-exact))
- common)
- (let ((ov (completion-preview--make-overlay
- end (completion-preview--propertize-for-mouse
- (concat (substring common (- end beg)) suffix)))))
- (overlay-put ov 'completion-preview-beg beg)
- (overlay-put ov 'completion-preview-end end)
- (overlay-put ov 'completion-preview-index 0)
- (overlay-put ov 'completion-preview-suffixes suffixes)
- (overlay-put ov 'completion-preview-common common)
- (overlay-put ov 'completion-preview-base base)
- (overlay-put ov 'completion-preview-props props)
- (completion-preview-active-mode)))))
+ (apply #'completion-preview-show beg end common suffixes base props)))
(defun completion-preview--try-update ()
"Try to update completion preview, but give up as soon as input arrives."
@@ -595,7 +578,7 @@ completion-preview--show
(substring cand (- end beg))))
'completion-preview-end end)
;; The previous preview is no longer applicable, hide it.
- (completion-preview-active-mode -1))))
+ (completion-preview-hide))))
;; Run `completion-at-point-functions' to get a new candidate.
(if completion-preview-idle-delay
(setq completion-preview--timer
@@ -622,7 +605,7 @@ completion-preview--post-command
(completion-preview-require-minimum-symbol-length)
(not buffer-read-only))
(completion-preview--show)
- (completion-preview-active-mode -1)))))
+ (completion-preview-hide)))))
(defun completion-preview--barf-if-no-preview ()
"Signal a `user-error' if completion preview is not active."
@@ -642,7 +625,7 @@ completion-preview-insert
:exit-function))
(aft (completion-preview--get 'after-string))
(str (concat pre com (nth ind all))))
- (completion-preview-active-mode -1)
+ (completion-preview-hide)
(goto-char end)
(insert-and-inherit (substring-no-properties aft))
(when (functionp efn) (funcall efn str 'finished))))
@@ -691,7 +674,7 @@ completion-preview-partial-insert
(efn (plist-get
(completion-preview--get 'completion-preview-props)
:exit-function)))
- (completion-preview-active-mode -1)
+ (completion-preview-hide)
(when (functionp efn) (funcall efn (concat pre com (nth ind all))
'finished))))
;; If we kept anything, update preview overlay accordingly.
@@ -756,7 +739,7 @@ completion-preview-complete
(props (plist-put props :exit-function
(when (functionp efn)
(lambda (string status)
- (completion-preview-active-mode -1)
+ (completion-preview-hide)
(funcall efn string status)))))
;; The predicate is meant for the original completion
;; candidates, which may be symbols or cons cells, but
@@ -778,7 +761,7 @@ completion-preview-complete
;; Remove stale preview since `efn' can make arbitrary
;; text and point modifications that might interfere with
;; a subsequent preview update. See bug#76606.
- (completion-preview-active-mode -1)
+ (completion-preview-hide)
(funcall efn (concat base com) (if (cdr all) 'exact 'finished)))
;; Otherwise, remove the common prefix from the preview.
(completion-preview--inhibit-update)
@@ -861,7 +844,7 @@ completion-preview-mode
(if completion-preview-mode
(add-hook 'post-command-hook #'completion-preview--post-command nil t)
(remove-hook 'post-command-hook #'completion-preview--post-command t)
- (when completion-preview-active-mode (completion-preview-active-mode -1))
+ (when completion-preview-active-mode (completion-preview-hide))
(when (timerp completion-preview--timer)
(cancel-timer completion-preview--timer)
(setq completion-preview--timer nil))))
@@ -882,5 +865,56 @@ global-completion-preview-mode
wdired-mode)
t))
+
+;;; API
+
+(defun completion-preview-show (beg end common suffixes &optional base &rest props)
+ "Display an inline completion preview.
+
+BEG and END are buffer positions, the beginning and end of the buffer
+text for which the preview shows a completion suggestion, respectively.
+The completion preview is displayed right after END.
+
+COMMON is a common prefix of all available completion candidates.
+SUFFIXES is a list of strings such that prepending COMMON to a suffix
+yields a completion candidate.
+
+The completion preview initially displays the first completion
+candidate, the candidate obtained by prepending COMMON to the first
+element of SUFFIXES.
+
+PROPS is a list of extra metadata, like `completion-extra-properties'.
+Currently the only meaningful property is `:exit-function'.
+
+Optional argument BASE, if non-nil, is an additional prefix to prepend
+to a completion suggestion you accept before reporting it to the given
+`:exit-function'. BASE does not influence completion."
+ (when-let* ((suffix (car suffixes)))
+ (set-text-properties 0 (length suffix)
+ (list 'face (if (cdr suffixes)
+ 'completion-preview
+ 'completion-preview-exact))
+ suffix)
+ (set-text-properties 0 (length common)
+ (list 'face (if (cdr suffixes)
+ 'completion-preview-common
+ 'completion-preview-exact))
+ common)
+ (let ((ov (completion-preview--make-overlay
+ end (completion-preview--propertize-for-mouse
+ (concat (substring common (- end beg)) suffix)))))
+ (overlay-put ov 'completion-preview-beg beg)
+ (overlay-put ov 'completion-preview-end end)
+ (overlay-put ov 'completion-preview-index 0)
+ (overlay-put ov 'completion-preview-suffixes suffixes)
+ (overlay-put ov 'completion-preview-common (or common ""))
+ (overlay-put ov 'completion-preview-base (or base ""))
+ (overlay-put ov 'completion-preview-props props)
+ (completion-preview-active-mode))))
+
+(defun completion-preview-hide ()
+ "Hide the completion preview and reset its state."
+ (completion-preview-active-mode -1))
+
(provide 'completion-preview)
;;; completion-preview.el ends here
--
2.48.1
--=-=-=--
bug-gnu-emacs@HIDDEN:bug#76941; Package emacs.
Full text available.Received: (at 76941) by debbugs.gnu.org; 11 Mar 2025 17:10:16 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Tue Mar 11 13:10:16 2025 Received: from localhost ([127.0.0.1]:45348 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1ts37Q-00088P-9L for submit <at> debbugs.gnu.org; Tue, 11 Mar 2025 13:10:16 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:41138) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from <eliz@HIDDEN>) id 1ts37N-00083o-5i for 76941 <at> debbugs.gnu.org; Tue, 11 Mar 2025 13:10:13 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from <eliz@HIDDEN>) id 1ts37H-000144-6I; Tue, 11 Mar 2025 13:10:07 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=gxf0WyXZG+E88MNdSkp7esowiVsyZAbYbffR4pjBHpA=; b=AtneM+3JJMrw HaP57/g6KMDd2GNg/iowSNt4RbtFiScrBTQRQGGb0n2XgP6XAoXgolZK8tcykFmAngzvdCRzczizl 3eXCkH1zw2vTmDucy9rhTElvqDw0DyTkfN60SBbhsHX9R54yr4lsMRKOBiGzrv5FAIFh31kYTzQXZ YKduWbF23e9rP1uTGSP9cTbeFznox8nf6awrnud9yP3w3LHYZ9/O1BTIRp8x187CVQt2b9NCxfraK UHXCxPowbZwslx8PT393A+1OFbq7HtrqbUrS2dbzp0oioTVmiphsNXi4K5WJn9g4nBs1cqDAYZOef 1ZideE61LmLSGGDGYVoC2w==; Date: Tue, 11 Mar 2025 19:09:39 +0200 Message-Id: <86cyenbijw.fsf@HIDDEN> From: Eli Zaretskii <eliz@HIDDEN> To: Eshel Yaron <me@HIDDEN> In-Reply-To: <m1o6y7hcq9.fsf@HIDDEN> (message from Eshel Yaron on Tue, 11 Mar 2025 15:18:54 +0100) Subject: Re: bug#76941: [PATCH] completion-preview.el: Provide an API. References: <m1y0xbhgrd.fsf@HIDDEN> <86plinbshg.fsf@HIDDEN> <m1o6y7hcq9.fsf@HIDDEN> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 76941 Cc: 76941 <at> debbugs.gnu.org X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -3.3 (---) > From: Eshel Yaron <me@HIDDEN> > Cc: 76941 <at> debbugs.gnu.org > Date: Tue, 11 Mar 2025 15:18:54 +0100 > > Eli Zaretskii <eliz@HIDDEN> writes: > > >> Date: Tue, 11 Mar 2025 13:51:50 +0100 > >> From: Eshel Yaron via "Bug reports for GNU Emacs, > >> the Swiss army knife of text editors" <bug-gnu-emacs@HIDDEN> > >> > >> This patch adds an initial API for controlling Completion Preview mode's > >> preview overlay from Lisp programs, so other features can reuse the > >> completion preview UI. > >> > >> Any thoughts/comments? > > > > Should this be documented in the ELisp manual? > > Maybe, I can definitely add something if you think we should. I wonder > where to mention it though, perhaps in `(elisp)Completion in Buffers'? Yes, there. Thanks.
bug-gnu-emacs@HIDDEN:bug#76941; Package emacs.
Full text available.Received: (at 76941) by debbugs.gnu.org; 11 Mar 2025 14:19:00 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Tue Mar 11 10:19:00 2025 Received: from localhost ([127.0.0.1]:44741 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1ts0Rf-000255-Q8 for submit <at> debbugs.gnu.org; Tue, 11 Mar 2025 10:19:00 -0400 Received: from mail.eshelyaron.com ([107.175.124.16]:57332 helo=eshelyaron.com) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from <me@HIDDEN>) id 1ts0Rd-00024w-IP for 76941 <at> debbugs.gnu.org; Tue, 11 Mar 2025 10:18:58 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com; s=mail; t=1741702737; bh=4qwAtgJ0Ww7xFsVOK86La4QtJ5kpOhBoSKkrgwHljf0=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=kauSRW37XDi5T2scZ1oq67ER6mmeoaWhx6K7mglTf6HMjoz/0x7Gak1pjbFaveeiJ eojasUvWsxlh0EjBuxawmA++K+TrdsVn8NVxslqUreSECb9IlxP2d5evc2iySjRyFk IPTeFFKUQh6pxT41EyNJGjAz4RlOuxbO3fCfR19mQdxEq3PsRrIcHmCsQ7FYzRFKtV 6jFbYv0kfsM5A35++x8sVSM6f/hJUG6aI/0FsKd0fPFNc106rL5c0Hu5/6JCHXGa9I hRHmTWdhGt68wCXWg2Cf4ZM462Mu5i8YiU5vMd4fTpr8fWfLGaRWqvh3ySKd355Iov 3FUWrZ+t/GdFg== From: Eshel Yaron <me@HIDDEN> To: Eli Zaretskii <eliz@HIDDEN> Subject: Re: bug#76941: [PATCH] completion-preview.el: Provide an API. In-Reply-To: <86plinbshg.fsf@HIDDEN> References: <m1y0xbhgrd.fsf@HIDDEN> <86plinbshg.fsf@HIDDEN> Date: Tue, 11 Mar 2025 15:18:54 +0100 Message-ID: <m1o6y7hcq9.fsf@HIDDEN> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 76941 Cc: 76941 <at> debbugs.gnu.org X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -1.0 (-) Hi Eli, Eli Zaretskii <eliz@HIDDEN> writes: >> Date: Tue, 11 Mar 2025 13:51:50 +0100 >> From: Eshel Yaron via "Bug reports for GNU Emacs, >> the Swiss army knife of text editors" <bug-gnu-emacs@HIDDEN> >> >> This patch adds an initial API for controlling Completion Preview mode's >> preview overlay from Lisp programs, so other features can reuse the >> completion preview UI. >> >> Any thoughts/comments? > > Should this be documented in the ELisp manual? Maybe, I can definitely add something if you think we should. I wonder where to mention it though, perhaps in `(elisp)Completion in Buffers'? Thanks, Eshel
bug-gnu-emacs@HIDDEN:bug#76941; Package emacs.
Full text available.Received: (at 76941) by debbugs.gnu.org; 11 Mar 2025 13:35:20 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Tue Mar 11 09:35:20 2025 Received: from localhost ([127.0.0.1]:42253 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1trzlP-00081l-S0 for submit <at> debbugs.gnu.org; Tue, 11 Mar 2025 09:35:20 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:56426) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from <eliz@HIDDEN>) id 1trzlN-00080k-Of for 76941 <at> debbugs.gnu.org; Tue, 11 Mar 2025 09:35:18 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from <eliz@HIDDEN>) id 1trzlG-000794-RL; Tue, 11 Mar 2025 09:35:12 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=fxbsAjeUfNyPhwZ0UOGRKA64TEp8djcZi+rJgfOrO48=; b=bCr2ke1S2Peo DQIqqIVhlR/nxRv0eFKDF8vyi2kUUcbRvyT3fuR3v8h12a0gKgsJ26yxSIHxMz5Rwo0nLb+N9wBD5 ge0/9UxxQRmpfnCT+SFSvRL8WfMuUJA3RXhuHRNt6UuU1d07X/HPbM+fYikyoY9WZHvXzixc+U5Fu rC9c8s+1+2ucVzfxqQDcNUlJBqaNKXE8r0ppc/YhdIeRDWUd7tmr8Vw5tiKAkDU+Ubzhe1EFBeuaD vY7AyOqKQqe+2F3u4RMx7oUX7jxdB6rnrxNBPdDzI6atrmayFHJwCsA160PfZTEviApfTSrp1354C yl+L9bbXZNJitzqzh8dqTQ==; Date: Tue, 11 Mar 2025 15:35:07 +0200 Message-Id: <86plinbshg.fsf@HIDDEN> From: Eli Zaretskii <eliz@HIDDEN> To: Eshel Yaron <me@HIDDEN> In-Reply-To: <m1y0xbhgrd.fsf@HIDDEN> (bug-gnu-emacs@HIDDEN) Subject: Re: bug#76941: [PATCH] completion-preview.el: Provide an API. References: <m1y0xbhgrd.fsf@HIDDEN> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 76941 Cc: 76941 <at> debbugs.gnu.org X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -3.3 (---) > Date: Tue, 11 Mar 2025 13:51:50 +0100 > From: Eshel Yaron via "Bug reports for GNU Emacs, > the Swiss army knife of text editors" <bug-gnu-emacs@HIDDEN> > > This patch adds an initial API for controlling Completion Preview mode's > preview overlay from Lisp programs, so other features can reuse the > completion preview UI. > > Any thoughts/comments? Should this be documented in the ELisp manual?
bug-gnu-emacs@HIDDEN:bug#76941; Package emacs.
Full text available.
Received: (at submit) by debbugs.gnu.org; 11 Mar 2025 12:52:10 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Mar 11 08:52:10 2025
Received: from localhost ([127.0.0.1]:42130 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1trz5e-0005on-3C
for submit <at> debbugs.gnu.org; Tue, 11 Mar 2025 08:52:10 -0400
Received: from lists.gnu.org ([2001:470:142::17]:36840)
by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.84_2) (envelope-from <me@HIDDEN>) id 1trz5a-0005o8-FR
for submit <at> debbugs.gnu.org; Tue, 11 Mar 2025 08:52:07 -0400
Received: from eggs.gnu.org ([2001:470:142:3::10])
by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <me@HIDDEN>) id 1trz5U-0004vB-FG
for bug-gnu-emacs@HIDDEN; Tue, 11 Mar 2025 08:52:00 -0400
Received: from mail.eshelyaron.com ([107.175.124.16] helo=eshelyaron.com)
by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <me@HIDDEN>) id 1trz5P-0006ho-R0
for bug-gnu-emacs@HIDDEN; Tue, 11 Mar 2025 08:52:00 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com;
s=mail; t=1741697512;
bh=hejyUu6myrAxf8QNEbBF/z/1qAu7CdRzE6WHTLdTrII=;
h=From:To:Subject:Date:From;
b=c1Y1F+4sEzljLyC4xK6fXq63vtFz2GWOlDuH5tit0yZgbBSQ4hrxhjVgH/jfglBSE
rasObPO/PQXhmgGmupZHKm7K1XVTso9oYfkQ2tS6csDjshSIyKlsgw7AYjHmhgmxbn
opEnWlFxeK90mC2rIOF/SBO9U3u40NRCdVKht6UKmaS6ugcCewcFLwfJGuWAGUUJKy
9dC3z4oCANUtOv4t1857WieVym/MQgNtJGpAOmEB1i+hdw0LAKXKu+YY4ivstuzDMU
yFDJmdBs8wdL4BynjOr8iVxoUQWPtE0dVUkGpbTTCguS5YgGBaILb9mYdFFPtjxOC3
6f4e/XdXGZ4sQ==
From: Eshel Yaron <me@HIDDEN>
To: bug-gnu-emacs@HIDDEN
Subject: [PATCH] completion-preview.el: Provide an API.
Date: Tue, 11 Mar 2025 13:51:50 +0100
Message-ID: <m1y0xbhgrd.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13)
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="=-=-="
Received-SPF: pass client-ip=107.175.124.16; envelope-from=me@HIDDEN;
helo=eshelyaron.com
X-Spam_score_int: -20
X-Spam_score: -2.1
X-Spam_bar: --
X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,
RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001,
SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-Spam-Score: 0.9 (/)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -0.1 (/)
--=-=-=
Content-Type: text/plain
Tags: patch
Hi,
This patch adds an initial API for controlling Completion Preview mode's
preview overlay from Lisp programs, so other features can reuse the
completion preview UI.
Any thoughts/comments?
--=-=-=
Content-Type: text/patch
Content-Disposition: attachment;
filename=0001-completion-preview.el-Provide-an-API.patch
From f1af366c007f52e35c5a9952640054af01882984 Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@HIDDEN>
Date: Tue, 11 Mar 2025 11:16:49 +0100
Subject: [PATCH] completion-preview.el: Provide an API.
Add new functions for summoning and dismissing the
completion preview programmatically. This lets Lisp code
leverage the completion preview UI for different use cases.
* lisp/completion-preview.el (completion-preview-show): New
function.
(completion-preview-hide): Rename to
'completion-preview--hide', use old name for new public API
function.
(completion-preview--hide): New name, see above.
(completion-preview-active-mode, completion-preview--update)
(completion-preview--show)
(completion-preview--window-selection-change)
(completion-preview--post-command, completion-preview-insert)
(completion-preview-partial-insert)
(completion-preview-complete, completion-preview-mode): Use
new functions to show/hide the preview.
* etc/NEWS: Announce new API functions.
---
etc/NEWS | 5 ++
lisp/completion-preview.el | 98 +++++++++++++++++++++++++-------------
2 files changed, 71 insertions(+), 32 deletions(-)
diff --git a/etc/NEWS b/etc/NEWS
index 926d426eaae..4f83114523f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -199,6 +199,11 @@ that your popup interface uses for a more integrated experience.
Note: 'completion-preview-sort-function' was present also in Emacs 30.1,
albeit as a variable, not a user option.
+---
+*** New functions 'completion-preview-show' and 'completion-preview-hide'.
+These new API functions allow Lisp programs to summon and dismiss the
+completion preview at will.
+
** Windows
+++
diff --git a/lisp/completion-preview.el b/lisp/completion-preview.el
index 8f7cba580ba..7d263e3678c 100644
--- a/lisp/completion-preview.el
+++ b/lisp/completion-preview.el
@@ -123,6 +123,10 @@
;; (lambda ()
;; (setq-local completion-preview-overlay-priority 1200)
;; (completion-preview-mode)))
+;;
+;; This library also provides an API that you can use to summon and
+;; dismiss the completion preview programmatically; see the functions
+;; `completion-preview-show' and `completion-preview-hide' for details.
;;; Code:
@@ -336,7 +340,7 @@ completion-preview-require-minimum-symbol-length
(and bounds (<= completion-preview-minimum-symbol-length
(- (cdr bounds) (car bounds)))))))
-(defun completion-preview-hide ()
+(defun completion-preview--hide ()
"Hide the completion preview."
(when completion-preview--overlay
(delete-overlay completion-preview--overlay)
@@ -418,7 +422,7 @@ completion-preview--window-selection-change
(unless (or (eq window (selected-window))
(eq window (minibuffer-selected-window)))
(with-current-buffer (window-buffer window)
- (completion-preview-active-mode -1))))
+ (completion-preview-hide))))
(define-minor-mode completion-preview-active-mode
"Mode for when the completion preview is shown."
@@ -435,7 +439,7 @@ completion-preview-active-mode
completion-preview-active-mode-map))
(remove-hook 'window-selection-change-functions
#'completion-preview--window-selection-change t)
- (completion-preview-hide)))
+ (completion-preview--hide)))
(defvar completion-preview-completion-styles '(basic)
"List of completion styles that Completion Preview mode uses.
@@ -521,28 +525,7 @@ completion-preview--update
(run-hook-wrapped
'completion-at-point-functions
#'completion-preview--capf-wrapper)
- (when-let* ((suffix (car suffixes)))
- (set-text-properties 0 (length suffix)
- (list 'face (if (cdr suffixes)
- 'completion-preview
- 'completion-preview-exact))
- suffix)
- (set-text-properties 0 (length common)
- (list 'face (if (cdr suffixes)
- 'completion-preview-common
- 'completion-preview-exact))
- common)
- (let ((ov (completion-preview--make-overlay
- end (completion-preview--propertize-for-mouse
- (concat (substring common (- end beg)) suffix)))))
- (overlay-put ov 'completion-preview-beg beg)
- (overlay-put ov 'completion-preview-end end)
- (overlay-put ov 'completion-preview-index 0)
- (overlay-put ov 'completion-preview-suffixes suffixes)
- (overlay-put ov 'completion-preview-common common)
- (overlay-put ov 'completion-preview-base base)
- (overlay-put ov 'completion-preview-props props)
- (completion-preview-active-mode)))))
+ (apply #'completion-preview-show beg end common suffixes base props)))
(defun completion-preview--try-update ()
"Try to update completion preview, but give up as soon as input arrives."
@@ -595,7 +578,7 @@ completion-preview--show
(substring cand (- end beg))))
'completion-preview-end end)
;; The previous preview is no longer applicable, hide it.
- (completion-preview-active-mode -1))))
+ (completion-preview-hide))))
;; Run `completion-at-point-functions' to get a new candidate.
(if completion-preview-idle-delay
(setq completion-preview--timer
@@ -622,7 +605,7 @@ completion-preview--post-command
(completion-preview-require-minimum-symbol-length)
(not buffer-read-only))
(completion-preview--show)
- (completion-preview-active-mode -1)))))
+ (completion-preview-hide)))))
(defun completion-preview--barf-if-no-preview ()
"Signal a `user-error' if completion preview is not active."
@@ -642,7 +625,7 @@ completion-preview-insert
:exit-function))
(aft (completion-preview--get 'after-string))
(str (concat pre com (nth ind all))))
- (completion-preview-active-mode -1)
+ (completion-preview-hide)
(goto-char end)
(insert-and-inherit (substring-no-properties aft))
(when (functionp efn) (funcall efn str 'finished))))
@@ -691,7 +674,7 @@ completion-preview-partial-insert
(efn (plist-get
(completion-preview--get 'completion-preview-props)
:exit-function)))
- (completion-preview-active-mode -1)
+ (completion-preview-hide)
(when (functionp efn) (funcall efn (concat pre com (nth ind all))
'finished))))
;; If we kept anything, update preview overlay accordingly.
@@ -756,7 +739,7 @@ completion-preview-complete
(props (plist-put props :exit-function
(when (functionp efn)
(lambda (string status)
- (completion-preview-active-mode -1)
+ (completion-preview-hide)
(funcall efn string status)))))
;; The predicate is meant for the original completion
;; candidates, which may be symbols or cons cells, but
@@ -778,7 +761,7 @@ completion-preview-complete
;; Remove stale preview since `efn' can make arbitrary
;; text and point modifications that might interfere with
;; a subsequent preview update. See bug#76606.
- (completion-preview-active-mode -1)
+ (completion-preview-hide)
(funcall efn (concat base com) (if (cdr all) 'exact 'finished)))
;; Otherwise, remove the common prefix from the preview.
(completion-preview--inhibit-update)
@@ -861,7 +844,7 @@ completion-preview-mode
(if completion-preview-mode
(add-hook 'post-command-hook #'completion-preview--post-command nil t)
(remove-hook 'post-command-hook #'completion-preview--post-command t)
- (when completion-preview-active-mode (completion-preview-active-mode -1))
+ (when completion-preview-active-mode (completion-preview-hide))
(when (timerp completion-preview--timer)
(cancel-timer completion-preview--timer)
(setq completion-preview--timer nil))))
@@ -882,5 +865,56 @@ global-completion-preview-mode
wdired-mode)
t))
+
+;;; API
+
+(defun completion-preview-show (beg end common suffixes &optional base &rest props)
+ "Display an inline completion preview.
+
+BEG and END are buffer positions, the beginning and end of the buffer
+text for which the preview shows a completion suggestion, respectively.
+The completion preview is displayed right after END.
+
+COMMON is a common prefix of all available completion candidates.
+SUFFIXES is a list of strings such that prepending COMMON to a suffix
+yields a completion candidate.
+
+The completion preview initially displays the first completion
+candidate, the candidate obtained by prepending COMMON to the first
+element of SUFFIXES.
+
+PROPS is a list of extra metadata, like `completion-extra-properties'.
+Currently the only meaningful property is `:exit-function'.
+
+Optional argument BASE, if non-nil, is an additional prefix to prepend
+to a completion suggestion you accept before reporting it to the given
+`:exit-function'. BASE does not influence completion."
+ (when-let* ((suffix (car suffixes)))
+ (set-text-properties 0 (length suffix)
+ (list 'face (if (cdr suffixes)
+ 'completion-preview
+ 'completion-preview-exact))
+ suffix)
+ (set-text-properties 0 (length common)
+ (list 'face (if (cdr suffixes)
+ 'completion-preview-common
+ 'completion-preview-exact))
+ common)
+ (let ((ov (completion-preview--make-overlay
+ end (completion-preview--propertize-for-mouse
+ (concat (substring common (- end beg)) suffix)))))
+ (overlay-put ov 'completion-preview-beg beg)
+ (overlay-put ov 'completion-preview-end end)
+ (overlay-put ov 'completion-preview-index 0)
+ (overlay-put ov 'completion-preview-suffixes suffixes)
+ (overlay-put ov 'completion-preview-common (or common ""))
+ (overlay-put ov 'completion-preview-base (or base ""))
+ (overlay-put ov 'completion-preview-props props)
+ (completion-preview-active-mode))))
+
+(defun completion-preview-hide ()
+ "Hide the completion preview and reset its state."
+ (completion-preview-active-mode -1))
+
(provide 'completion-preview)
;;; completion-preview.el ends here
--
2.48.1
--=-=-=--
Eshel Yaron <me@HIDDEN>:bug-gnu-emacs@HIDDEN.
Full text available.bug-gnu-emacs@HIDDEN:bug#76941; Package emacs.
Full text available.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997 nCipher Corporation Ltd,
1994-97 Ian Jackson.