master 18de131222e: Support more metadata properties in completion-category-overrides (bug#68214)

[Juri Linkov]

branch: master
commit 18de131222ee24c4088ac45be1babad26284af5b
Author: Juri Linkov <juri@linkov.net>
Commit: Juri Linkov <juri@linkov.net>

    Support more metadata properties in completion-category-overrides 
(bug#68214)
    
    * doc/lispref/minibuf.texi (Completion Variables): Add
    to the table of completion-category-overrides new items:
    `cycle-sort-function', `group-function', `annotation-function',
    `affixation-function'.
    
    * lisp/minibuffer.el (completion-metadata-get): Try also to get
    the property from completion-category-overrides by category.
    Suggested by Daniel Mendler <mail@daniel-mendler.de>.
    (completion-category-defaults): Add new properties to docstring.
    (completion-category-overrides): Add customization for new
    properties: `cycle-sort-function', `group-function',
    `annotation-function', `affixation-function'.
    (completion-metadata-override-get): Remove function.
    (minibuffer-completion-help): Replace 'completion-metadata-override-get'
    with 'completion-metadata-get' for 'display-sort-function'.
---
 doc/lispref/minibuf.texi | 15 +++++++++++++-
 etc/NEWS                 | 10 ++++++----
 lisp/minibuffer.el       | 51 +++++++++++++++++++++++++++++++++++++-----------
 3 files changed, 60 insertions(+), 16 deletions(-)

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 8aed1515764..8d25a53161e 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1879,17 +1879,30 @@ The value should be a value for 
@code{completion-cycle-threshold}
 (@pxref{Completion Options,,, emacs, The GNU Emacs Manual}) for this
 category.
 
+@item cycle-sort-function
+The function to sort entries when cycling.
+
 @item display-sort-function
+The function to sort entries in the @file{*Completions*} buffer.
 The possible values are: @code{nil}, which means to use either the
 sorting function from metadata or if that is @code{nil}, fall back to
 @code{completions-sort}; @code{identity}, which means not to sort at
 all, leaving the original order; or any other value out of those used
 in @code{completions-sort} (@pxref{Completion Options,,, emacs, The
 GNU Emacs Manual}).
+
+@item group-function
+The function to group completions.
+
+@item annotation-function
+The function to add annotations to completions.
+
+@item affixation-function
+The function to add prefixes and suffixes to completions.
 @end table
 
 @noindent
-Additional alist entries may be defined in the future.
+See @ref{Programmed Completion}, for a complete list of metadata entries.
 @end defopt
 
 @defvar completion-extra-properties
diff --git a/etc/NEWS b/etc/NEWS
index 3a1168f62b3..c3d777b971f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -745,10 +745,12 @@ will be first sorted alphabetically, and then re-sorted 
by their order
 in the minibuffer history, with more recent candidates appearing first.
 
 +++
-*** 'completion-category-overrides' supports 'display-sort-function'.
-You can now customize the sorting order for any category in
-'completion-category-overrides' that will override the sorting order
-defined in the metadata or in 'completions-sort'.
+*** 'completion-category-overrides' supports more metadata.
+The new supported completion properties are 'cycle-sort-function',
+'display-sort-function', 'annotation-function', 'affixation-function',
+'group-function'.  You can now customize them for any category in
+'completion-category-overrides' that will override the properties
+defined in completion metadata.
 
 ** Pcomplete
 
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index b7aebae63a8..04b36f03d11 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -151,7 +151,15 @@ The metadata of a completion table should be constant 
between two boundaries."
                        minibuffer-completion-predicate))
 
 (defun completion-metadata-get (metadata prop)
-  (cdr (assq prop metadata)))
+  "Get PROP from completion METADATA.
+If the metadata specifies a completion category, the variables
+`completion-category-overrides' and
+`completion-category-defaults' take precedence."
+  (if-let (((not (eq prop 'category)))
+           (cat (alist-get 'category metadata))
+           (over (completion--category-override cat prop)))
+      (cdr over)
+    (alist-get prop metadata)))
 
 (defun complete-with-action (action collection string predicate)
   "Perform completion according to ACTION.
@@ -1138,27 +1146,38 @@ styles for specific categories, such as files, buffers, 
etc."
     (symbol-help (styles . (basic shorthand substring)))
     (calendar-month (display-sort-function . identity)))
   "Default settings for specific completion categories.
+
 Each entry has the shape (CATEGORY . ALIST) where ALIST is
 an association list that can specify properties such as:
 - `styles': the list of `completion-styles' to use for that category.
 - `cycle': the `completion-cycle-threshold' to use for that category.
-- `display-sort-function': the sorting function.
+- `cycle-sort-function': function to sort entries when cycling.
+- `display-sort-function': function to sort entries in *Completions*.
+- `group-function': function for grouping the completion candidates.
+- `annotation-function': function to add annotations in *Completions*.
+- `affixation-function': function to prepend/append a prefix/suffix.
+
 Categories are symbols such as `buffer' and `file', used when
 completing buffer and file names, respectively.
 
 Also see `completion-category-overrides'.")
 
 (defcustom completion-category-overrides nil
-  "List of category-specific user overrides for completion styles.
+  "List of category-specific user overrides for completion metadata.
 
 Each override has the shape (CATEGORY . ALIST) where ALIST is
 an association list that can specify properties such as:
 - `styles': the list of `completion-styles' to use for that category.
 - `cycle': the `completion-cycle-threshold' to use for that category.
+- `cycle-sort-function': function to sort entries when cycling.
 - `display-sort-function': nil means to use either the sorting
 function from metadata, or if that is nil, fall back to `completions-sort';
 `identity' disables sorting and keeps the original order; and other
 possible values are the same as in `completions-sort'.
+- `group-function': function for grouping the completion candidates.
+- `annotation-function': function to add annotations in *Completions*.
+- `affixation-function': function to prepend/append a prefix/suffix.
+See more description of metadata in `completion-metadata'.
 
 Categories are symbols such as `buffer' and `file', used when
 completing buffer and file names, respectively.
@@ -1180,6 +1199,10 @@ overrides the default specified in 
`completion-category-defaults'."
            (cons :tag "Completion Cycling"
                 (const :tag "Select one value from the menu." cycle)
                  ,completion--cycling-threshold-type)
+           (cons :tag "Cycle Sorting"
+                 (const :tag "Select one value from the menu."
+                        cycle-sort-function)
+                 (choice (function :tag "Custom function")))
            (cons :tag "Completion Sorting"
                  (const :tag "Select one value from the menu."
                         display-sort-function)
@@ -1189,18 +1212,24 @@ overrides the default specified in 
`completion-category-defaults'."
                                 minibuffer-sort-alphabetically)
                          (const :tag "Historical sorting"
                                 minibuffer-sort-by-history)
-                         (function :tag "Custom function"))))))
+                         (function :tag "Custom function")))
+           (cons :tag "Completion Groups"
+                 (const :tag "Select one value from the menu."
+                        group-function)
+                 (choice (function :tag "Custom function")))
+           (cons :tag "Completion Annotation"
+                 (const :tag "Select one value from the menu."
+                        annotation-function)
+                 (choice (function :tag "Custom function")))
+           (cons :tag "Completion Affixation"
+                 (const :tag "Select one value from the menu."
+                        affixation-function)
+                 (choice (function :tag "Custom function"))))))
 
 (defun completion--category-override (category tag)
   (or (assq tag (cdr (assq category completion-category-overrides)))
       (assq tag (cdr (assq category completion-category-defaults)))))
 
-(defun completion-metadata-override-get (metadata prop)
-  (if-let ((cat (completion-metadata-get metadata 'category))
-           (over (completion--category-override cat prop)))
-      (cdr over)
-    (completion-metadata-get metadata prop)))
-
 (defun completion--styles (metadata)
   (let* ((cat (completion-metadata-get metadata 'category))
          (over (completion--category-override cat 'styles)))
@@ -2546,7 +2575,7 @@ The candidate will still be chosen by `choose-completion' 
unless
              (aff-fun (or (completion-metadata-get all-md 'affixation-function)
                           (plist-get completion-extra-properties
                                      :affixation-function)))
-             (sort-fun (completion-metadata-override-get all-md 
'display-sort-function))
+             (sort-fun (completion-metadata-get all-md 'display-sort-function))
              (group-fun (completion-metadata-get all-md 'group-function))
              (mainbuf (current-buffer))
              ;; If the *Completions* buffer is shown in a new