feature/minibuffer-completion-enhancements fd705bffffa 04/35: Add Completions Auto Update minor mode

[Eshel Yaron]

branch: feature/minibuffer-completion-enhancements
commit fd705bffffab69259fe08e17f555c5f24d532b3c
Author: Eshel Yaron <me@eshelyaron.com>
Commit: Eshel Yaron <me@eshelyaron.com>

    Add Completions Auto Update minor mode
    
    This adds a new global minor that updates the *Completions* buffer as
    you type in the minibuffer.
    
    * lisp/minibuffer.el (completions-auto-update-idle-time): New option.
    (completions-auto-update-timer): New buffer-local variable.
    (completions-auto-update)
    (completions-auto-update-start-timer)
    (completions-auto-update-setup)
    (completions-auto-update-exit): New functions.
    (completions-auto-update-mode): New global minor mode.
    * doc/emacs/mini.texi (Completion Options): Document it.
    * etc/NEWS: Announce it.
---
 doc/emacs/mini.texi | 30 ++++++++++++++++++++++--------
 etc/NEWS            |  4 ++++
 lisp/minibuffer.el  | 44 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 70 insertions(+), 8 deletions(-)

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index 0fbecd6cfde..d635208fc8b 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -735,14 +735,19 @@ completion alternatives in the completion list.
 @pxref{Shell Options}.
 
 @vindex completion-auto-help
-  If @code{completion-auto-help} is set to @code{nil}, the completion
-commands never display the completion list buffer; you must type
-@kbd{?} to display the list.  If the value is @code{lazy}, Emacs only
-shows the completion list buffer on the second attempt to complete.
-In other words, if there is nothing to complete, the first @key{TAB}
-echoes @samp{Next char not unique}; the second @key{TAB} shows the
-completion list buffer.  If the value is @code{always}, the completion
-list buffer is always shown when completion is attempted.
+  Emacs can show the @samp{*Completions*} buffer automatically in
+certain conditions.  You can control this behavior by customizing the
+user option @code{completion-auto-help}.  By default, this option is
+set to @code{t}, which says to show the @samp{*Completions*} buffer
+when you try to complete the minibuffer input and there is more then
+one way to complete your input.  If the value is @code{lazy}, Emacs
+only shows the @samp{*Completions*} buffer on the second attempt to
+complete---the first @key{TAB} echoes @samp{Next char not unique}, and
+the second @key{TAB} shows the completion list buffer.  If the value
+is @code{always}, Emacs shows the @samp{*Completions*} buffer whenever
+you invoke completion.  If @code{completion-auto-help} is set to
+@code{nil}, the completion commands never display the completion list
+buffer; you must type @kbd{?} to display the list.
 
 The display of the completion list buffer after it is shown for the
 first time is also controlled by @code{completion-auto-help}.  If the
@@ -755,6 +760,15 @@ the completion.  The value @code{visible} is a hybrid: it 
behaves like
 completion list buffer, and like @code{always} when it decides whether
 to pop it down.
 
+@cindex Completions Auto Update minor mode
+@findex completions-auto-update-mode
+  Beyond showing the @samp{*Completions*} buffer when you invoke
+completion commands with non-@code{nil} @samp{completion-auto-help},
+Emacs also provides the Completions Auto Update minor mode that
+updates the @samp{*Completions*} buffer to reflect your new input as
+you type in the minibuffer.  To enable Completions Auto Update mode,
+type @kbd{M-x completions-auto-update-mode}.
+
 @vindex completion-auto-select
   Emacs can optionally select the window showing the completions when
 it shows that window.  To enable this behavior, customize the user
diff --git a/etc/NEWS b/etc/NEWS
index 2dbcd36313b..80f68b4526d 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -787,6 +787,10 @@ in the minibuffer to restrict the list of possible 
completions to only
 include candidates matching the current minibuffer input.  See the
 Info node "(emacs) Narrow Completions" for more information.
 
+*** New minor mode 'completions-auto-update-mode'.
+This global minor mode automatically updates the *Completions* buffer
+as you type in the minibuffer.
+
 ** Pcomplete
 
 ---
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index af61694e923..289cbb72294 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -5363,6 +5363,50 @@ interactions is customizable via 
`minibuffer-regexp-prompts'."
     (remove-hook 'minibuffer-setup-hook #'minibuffer--regexp-setup)
     (remove-hook 'minibuffer-exit-hook #'minibuffer--regexp-exit)))
 
+(defcustom completions-auto-update-idle-time 0.2
+  "Number of seconds of idle to wait for before updating *Completions*.
+This applies to `completions-auto-update-mode', which see."
+  :group 'minibuffer
+  :type 'number)
+
+(defvar-local completions-auto-update-timer nil)
+
+(defun completions-auto-update ()
+  "Update the *Completions* buffer, if it is visible."
+  (when (get-buffer-window "*Completions*" 0)
+    (if completion-in-region-mode
+        (completion-help-at-point)
+      (minibuffer-completion-help)))
+  (setq completions-auto-update-timer nil))
+
+(defun completions-auto-update-start-timer ()
+  "Start an idle timer for updating *Completions*."
+  (and (null completions-auto-update-timer)
+       (get-buffer-window "*Completions*" 0)
+       (setq completions-auto-update-timer
+             (run-with-idle-timer completions-auto-update-idle-time
+                                  nil #'completions-auto-update))))
+
+(defun completions-auto-update-setup ()
+  "Prepare for updating *Completions* as you type in the minibuffer."
+  (add-hook 'post-self-insert-hook
+            #'completions-auto-update-start-timer nil t))
+
+(defun completions-auto-update-exit ()
+  "Stop updating *Completions* as you type in the minibuffer."
+  (remove-hook 'post-self-insert-hook
+               #'completions-auto-update-start-timer t))
+
+(define-minor-mode completions-auto-update-mode
+  "Update the *Completions* buffer as you type in the minibuffer."
+  :global t
+  (if completions-auto-update-mode
+      (progn
+        (add-hook 'minibuffer-setup-hook #'completions-auto-update-setup)
+        (add-hook 'minibuffer-exit-hook #'completions-auto-update-exit))
+    (remove-hook 'minibuffer-setup-hook #'completions-auto-update-setup)
+    (remove-hook 'minibuffer-exit-hook #'completions-auto-update-exit)))
+
 (provide 'minibuffer)
 
 ;;; minibuffer.el ends here