From d8e037eeaa7eef26349bc0fb3fa00e10a5c4b894 Mon Sep 17 00:00:00 2001 From: Daniel Mendler Date: Tue, 27 Apr 2021 19:44:41 +0300 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. * lisp/simple.el (read-extended-command--affixation): Return three-element lists. https://lists.gnu.org/archive/html/emacs-devel/2021-04/msg01193.html --- doc/lispref/minibuf.texi | 16 ++++++---------- lisp/minibuffer.el | 18 +++++++++--------- lisp/simple.el | 7 +++++-- 3 files changed, 20 insertions(+), 21 deletions(-) diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 72f0e5878b4..bc8868b58d2 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -1819,12 +1819,10 @@ default to that string. @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. @@ -1942,10 +1940,8 @@ completions. The function should take one argument, return such a list of @var{completions} where each element contains a list of three elements: a completion, a prefix which is displayed before the completion string in the @file{*Completions*} buffer, and -a suffix displayed after the completion 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}. +a suffix displayed after the completion string. This function +takes priority over @code{annotation-function}. @item display-sort-function The value should be a function for sorting completions. The function diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el index 98691c2ede5..24006249530 100644 --- a/lisp/minibuffer.el +++ b/lisp/minibuffer.el @@ -122,10 +122,10 @@ This metadata is an alist. Currently understood keys are: 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 @@ These include: `: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. diff --git a/lisp/simple.el b/lisp/simple.el index 999755a642f..26eb8cad7f8 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -2080,8 +2080,11 @@ or (if one of MODES is a minor mode), if it is switched on in BUFFER." (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.39.5