New customization variable `completion-eager-display'

The customization option can be set to t or nil, to respectively
always or never show the *Completions* buffer eagerly at the
beginning of a completion session.  Furthermore the option can
be set to the value auto.  In this case the *Completions* buffer
will only be shown if requested by the completion table.
Completion tables can use the `eager-display' completion
metadata to do so.  (Bug#74616, Bug#74617)

* lisp/minibuffer.el (completion-eager-display): New
customization variable.
(completion-metadata): Update docstring, document the
new `eager-display' completion metadata.
(completion-extra-properties): Update docstring, document the
new `:eager-display' completion metadata.
(completion-category-overrides): Add `eager-display' to the
custom type specification.
(completing-read-default): Handle the `completion-eager-display'
customization variable and the `eager-display' completion
metadata.
(completion-table-with-metadata): New function to create
a completion table with metadata.
(minibuffer-complete-defaults, minibuffer-complete-history):
Use it.
* lisp/ffap.el (ffap-menu-ask): Add `ffap-menu' completion
category and `eager-display' completion metadata.  Use
`completion-table-with-metadata'.
* lisp/imenu.el (imenu-eager-completion-buffer): Correct
docstring, which had been inverted.
(imenu--completion-buffer): Add `eager-display' completion
metadata.  Use `completion-table-with-metadata'.
* lisp/tmm.el (tmm-prompt): Add `tmm' completion category and
`eager-display' completion metadata.  Use
`completion-table-with-metadata'.  Add keymap setup.
(tmm-add-prompt): Remove keymap setup.
(tmm-goto-completions): Call `tmm-add-prompt' to ensure that a
*Completions* buffer is shown.
(tmm--completion-table): Remove unused internal function.
* etc/NEWS: Announce the change.

(cherry picked from commit fd021c07606264a73cd4c1f6fa6fe80a756defe0)

diff --git a/lisp/imenu.el b/lisp/imenu.el
index 536ccef96eaae5dd6251a3570fef62802af3cdd8..b58efa36bf1c1d7c12ac9155173b627b427f6f5d 100644 (file)
--- a/lisp/imenu.el
+++ b/lisp/imenu.el
@@ -714,21 +714,19 @@ Return one of the entries in index-alist or nil."
                    (cdr item)))
            index-alist))))
     (unless prompt (setq prompt (format-prompt "Index item" nil)))
-    (when-let ((name (minibuffer-with-setup-hook
-                         (lambda ()
-                           (setq-local
-                            completion-extra-properties
-                            `( :category imenu
-                               ,@(and imenu-flatten
-                                      completions-group
-                                      `(:group-function
-                                        ,(lambda (s transform)
-                                           (get-text-property
-                                            0 (if transform 'imenu-base-name 'imenu-section) s))))))
-                           (when imenu-eager-completion-buffer
-                             ;; Display the completion buffer.
-                             (minibuffer-completion-help)))
-                       (completing-read prompt prepared-index-alist nil t nil 'imenu--history))))
+    (when-let ((name (completing-read
+                      prompt
+                      (completion-table-with-metadata
+                      prepared-index-alist
+                       `((category . imenu)
+                         (eager-display . ,imenu-eager-completion-buffer)
+                         ,@(and imenu-flatten
+                                completions-group
+                                `((group-function
+                                   . ,(lambda (s transform)
+                                        (get-text-property
+                                         0 (if transform 'imenu-base-name 'imenu-section) s)))))))
+                     nil t nil 'imenu--history)))
       (setq choice (assoc name prepared-index-alist))
       (if (imenu--subalist-p choice)
          (imenu--completion-buffer (cdr choice) prompt)

diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index e987ede65f51049728b92c8ba0caaf561290665f..c23e7e767cd048684867f3f6bf9baccb1006a2cd 100644 (file)
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -1052,6 +1052,25 @@ If the current buffer is not a minibuffer, erase its entire contents."
 (defvar completion-show-inline-help t
   "If non-nil, print helpful inline messages during completion.")
 
+(defcustom completion-eager-display 'auto
+  "Whether completion commands should display *Completions* buffer eagerly.
+
+If the variable is set to t, completion commands show the *Completions*
+buffer always immediately.  Setting the variable to nil disables the
+eager *Completions* display for all commands.
+
+For the value `auto', completion commands show the *Completions* buffer
+immediately only if requested by the completion command.  Completion
+tables can request eager display via the `eager-display' metadata.
+
+See also the variables `completion-category-overrides' and
+`completion-extra-properties' for the `eager-display' completion
+metadata."
+  :type '(choice (const :tag "Never show *Completions* eagerly" nil)
+                 (const :tag "Always show *Completions* eagerly" t)
+                 (const :tag "If requested by the completion command" auto))
+  :version "31.1")
+
 (defcustom completion-auto-help t
   "Non-nil means automatically provide help for invalid completion input.
 If the value is t, the *Completions* buffer is displayed whenever completion
@@ -2770,6 +2789,8 @@ These include:
 
 `:narrow-completions-function': function for narrowing the completions list.
 
+`:eager-display': Show the *Completions* buffer eagerly.
+
 See more information about these functions above
 in `completion-metadata'.
 
@@ -5496,7 +5517,17 @@ See `completing-read' for the meaning of the arguments."
                 (setq-local minibuffer--require-match require-match)
                 (setq-local minibuffer--original-buffer buffer)
                 (add-hook 'minibuffer-exit-hook
-                          #'minibuffer-kill-completions-buffer nil t))
+                          #'minibuffer-kill-completions-buffer nil t)
+                ;; Show the completion help eagerly if
+                ;; `completion-eager-display' is t or if eager display
+                ;; has been requested by the completion table.
+                (when completion-eager-display
+                  (let* ((md (completion-metadata (or initial-input "")
+                                                  collection predicate))
+                         (fun (completion-metadata-get md 'eager-display)))
+                    (when (or fun (eq completion-eager-display t))
+                      (funcall (if (functionp fun)
+                                   fun #'minibuffer-completion-help))))))
             (read-from-minibuffer prompt initial-input keymap
                                   nil hist def inherit-input-method))))
     (when (and (equal result "") def)