From: Daniel Mendler <mail@daniel-mendler.de>
To: emacs-devel@gnu.org
Cc: Stefan Monnier <monnier@iro.umontreal.ca>, Juri Linkov <juri@linkov.net>
Subject: [PATCH] `affixation-function`: Allow only three-element lists
Date: Sun, 25 Apr 2021 02:39:53 +0200 [thread overview]
Message-ID: <e79d94cd-7829-0ac5-b86e-9314a21f3e39@daniel-mendler.de> (raw)
[-- Attachment #1: Type: text/plain, Size: 375 bytes --]
Regarding our previous discussion: I attached a patch which restricts
the definition of the `affixation-function` such that the returned list
must consist only of three-element lists. Since the
`affixation-function` is part of the widely used `completing-read` API a
simplification is helpful for both authors of completion UIs and authors
of completion tables.
Daniel
[-- Attachment #2: 0001-affixation-function-Allow-only-three-element-list-el.patch --]
[-- Type: text/x-diff, Size: 5302 bytes --]
From 82583ee3afbb1278e664a3e5858a93bc698c370b Mon Sep 17 00:00:00 2001
From: Daniel Mendler <mail@daniel-mendler.de>
Date: Sun, 25 Apr 2021 02:04:23 +0200
Subject: [PATCH] (affixation-function): Allow only three-element list elements
Restrict the definition of the `affixation-function`. The function
must return a list of three element lists. Since the
`affixation-function` is part of the widely used `completing-read` API
a simplification is helpful for both authors of completion UIs and
authors of completion tables.
* doc/lispref/minibuf.texi: Update documentation.
* lisp/minibuffer.el: Update documentation.
(minibuffer-completion-help): Add assertion.
* lisp/simple.el (read-extended-command--affixation): Return
three-element lists.
---
doc/lispref/minibuf.texi | 10 ++++------
lisp/minibuffer.el | 22 ++++++++++++----------
lisp/simple.el | 7 +++++--
3 files changed, 21 insertions(+), 18 deletions(-)
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 7cf2fcf68f..28d3afac22 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1819,12 +1819,10 @@ Completion Variables
@item :affixation-function
The value should be a function to add prefixes and suffixes to
completions. This function must accept one argument, a list of
-completions, and should return such a list of completions where
-each element contains a list of three elements: a completion,
-a prefix string, and a suffix string. When this function
-returns a list of two elements, it is interpreted as a list
-of a completion and a suffix string like in @code{:annotation-function}.
-This function takes priority over @code{:annotation-function}.
+completions, and should return a list of annotated completions. Each
+element of the returned list must be a three-element list, the
+completion, a prefix string, and a suffix string. This function takes
+priority over @code{:annotation-function}.
@item :exit-function
The value should be a function to run after performing completion.
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 98691c2ede..f76ce37030 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -122,10 +122,10 @@ completion-metadata
returns a string to append to STRING.
- `affixation-function': function to prepend/append a prefix/suffix to
entries. Takes one argument (COMPLETIONS) and should return a list
- of completions with a list of either two elements: completion
- and suffix, or three elements: completion, its prefix
- and suffix. This function takes priority over `annotation-function'
- when both are provided, so only this function is used.
+ of annotated completions. The elements of the list must be
+ three-element lists: completion, its prefix and suffix. This
+ function takes priority over `annotation-function' when both are
+ provided, so only this function is used.
- `display-sort-function': function to sort entries in *Completions*.
Takes one argument (COMPLETIONS) and should return a new list
of completions. Can operate destructively.
@@ -1972,11 +1972,11 @@ completion-extra-properties
`:affixation-function': Function to prepend/append a prefix/suffix to
completions. The function must accept one argument, a list of
- completions, and return a list where each element is a list of
- either two elements: a completion, and a suffix, or
- three elements: a completion, a prefix and a suffix.
- This function takes priority over `:annotation-function'
- when both are provided, so only this function is used.
+ completions, and return a list of annotated completions. The
+ elements of the list must be three-element lists: completion, its
+ prefix and suffix. This function takes priority over
+ `:annotation-function' when both are provided, so only this
+ function is used.
`:exit-function': Function to run after completion is performed.
@@ -2110,7 +2110,9 @@ minibuffer-completion-help
(cond
(aff-fun
(setq completions
- (funcall aff-fun completions)))
+ (funcall aff-fun completions))
+ (cl-assert (or (not completions)
+ (= 3 (length (car completions))))))
(ann-fun
(setq completions
(mapcar (lambda (s)
diff --git a/lisp/simple.el b/lisp/simple.el
index 999755a642..26eb8cad7f 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -2080,8 +2080,11 @@ read-extended-command--affixation
(obsolete
(format " (%s)" (car obsolete)))
((and binding (not (stringp binding)))
- (format " (%s)" (key-description binding))))))
- (if suffix (list command-name suffix) command-name)))
+ (format " (%s)" (key-description binding)))
+ (t ""))))
+ (put-text-property 0 (length suffix)
+ 'face 'completions-annotations suffix)
+ (list command-name "" suffix)))
command-names)))
(defcustom suggest-key-bindings t
--
2.20.1
next reply other threads:[~2021-04-25 0:39 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-25 0:39 Daniel Mendler [this message]
2021-04-25 17:46 ` [PATCH] `affixation-function`: Allow only three-element lists Juri Linkov
2021-04-25 18:02 ` Daniel Mendler
2021-04-25 20:34 ` Juri Linkov
2021-04-25 21:04 ` Daniel Mendler
2021-04-27 16:45 ` Juri Linkov
2021-04-27 17:40 ` Daniel Mendler
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=e79d94cd-7829-0ac5-b86e-9314a21f3e39@daniel-mendler.de \
--to=mail@daniel-mendler.de \
--cc=emacs-devel@gnu.org \
--cc=juri@linkov.net \
--cc=monnier@iro.umontreal.ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).