Re: on helm substantial differences

[Juri Linkov]

>> Before knowing what's the best approach, I think we should clearly
>> decide what would be the "ideal" new API.  E.g. should it return "any
>> string" and then it'd be up to the infrastructure code to store
>> side-info about what is the corresponding candidate's actual text?
>
> After trying different variants, it turned out that the most convenient
> is to use annotation-function that can contain a placeholder for the
> completion candidate.  Currently "%s" is used as a placeholder,
> for example, "prefix %s suffix" but it can be any string.

Actually, I discovered that unfortunately annotation-function
is unsuitable for formatting data in a columnar format.
It needs to receive a complete list of completions to be able
to adjust their widths for more optimal overall columnar layout.

So a new function is needed that is like annotation-function
but accepts a list of all completions.  There is an existing
similar function 'display-sort-function' that could be abused
to add prefix/suffix annotations, but maybe a separate function
would be preferable for cleaner API?

diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index e18c5c1372..c671750e9a 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -117,6 +117,9 @@ completion-metadata
 - `annotation-function': function to add annotations in *Completions*.
    Takes one argument (STRING), which is a possible completion and
    returns a string to append to STRING.
+- `display-function': function to display entries in *Completions*.
+   Takes one argument (COMPLETIONS) and should return a list
+   of completions with a placeholder that separates prefix/suffix.
 - `display-sort-function': function to sort entries in *Completions*.
    Takes one argument (COMPLETIONS) and should return a new list
    of completions.  Can operate destructively.
@@ -1885,6 +1888,9 @@ completion-extra-properties
    completion).  The function can access the completion data via
    `minibuffer-completion-table' and related variables.
 
+`:display-function': Function to display completions.
+   The function must accept one argument, a list of completions.
+
 `:exit-function': Function to run after completion is performed.
 
    The function must accept two arguments, STRING and STATUS.
@@ -1971,6 +1977,9 @@ minibuffer-completion-help
                        (plist-get completion-extra-properties
                                   :annotation-function)
                        completion-annotate-function))
+             (dfun (or (completion-metadata-get all-md 'display-function)
+                       (plist-get completion-extra-properties
+                                  :display-function)))
              (mainbuf (current-buffer))
              ;; If the *Completions* buffer is shown in a new
              ;; window, mark it as softly-dedicated, so bury-buffer in
@@ -2017,6 +2026,9 @@ minibuffer-completion-help
                                         (let ((ann (funcall afun s)))
                                           (if ann (list s ann) s)))
                                       completions)))
+                      (when dfun
+                        (setq completions
+                              (funcall dfun completions)))
 
                       (with-current-buffer standard-output
                         (set (make-local-variable 'completion-base-position)