[nongnu] elpa/vcomplete d9c97a5889 2/5: Integrate built-in completion enhancements of Emacs 29

[ELPA Syncer]

branch: elpa/vcomplete
commit d9c97a58892a67d5d258f8c189ee4364e279919e
Author: Daniel Semyonov <daniel@dsemy.com>
Commit: Daniel Semyonov <daniel@dsemy.com>

    Integrate built-in completion enhancements of Emacs 29
    
    * vcomplete.el (vcomplete-no-update-commands): Add Emacs 29+ commands
    to default value.
    (vcomplete-search-range): Don't define on Emacs 29+ and change
    default value.
    (vcomplete-highlight): Change default to inherit from
    'completions-highlight-face' if available.
    (vcomplete--get-completions-window, vcomplete--last-completion-overlay)
    (vcomplete--highlight-completion-at-point, vcomplete--move-n-completions)
    (vcomplete-next-completion, vcomplete-prev-completion)
    (vcomplete-choose-completion): Don't define on Emacs 29+.
    (vcomplete-with-completions-window): Alias to
    'with-minibuffer-completions-window' on Emacs 29+.
    (vcomplete-command-map): Use built-in command on Emacs 29+.
    (vcomplete--disable-completion-in-region): Don't use
    'vcomplete--get-completions-window' on Emacs 29+.
    (vcomplete--setup-completions): Ensure highlighting is enabled on
    Emacs 29+
    (vcomplete--reset-completions):
    (vcomplete--kill-completions): New function replacing
    'vcomplete--reset-completions'.
    (vcomplete-mode): Use 'vcomplete--kill-completions'.
    * README:
    * vcomplete.texi (Top, Introduction): Reword introduction.
    (Installing from the Git repository): Add information about automatic
    builds.
    (Usage, Customization, Completion commands): Add information about
    Emacs 29+ integration.
---
 NEWS           |  14 ++++
 README         |   5 +-
 vcomplete.el   | 234 ++++++++++++++++++++++++++++++++++-----------------------
 vcomplete.texi |  96 ++++++++++++-----------
 4 files changed, 209 insertions(+), 140 deletions(-)

diff --git a/NEWS b/NEWS
index 4aa013cf11..8a89b98761 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,20 @@
 Vcomplete NEWS -- history of user-visible changes. -*- mode: outline -*-
 See the end of the file for an explanation of the versioning scheme.
 
+* 2.0
+
+** Support built-in completion enhancements introduced in Emacs 29.
+Built-in commands are now used when available.  Completions are
+highlighted using built-in facilities when available.
+
+** Breaking changes
+
+*** 'vcomplete-with-completions-buffer' has been replaced with
+'vcomplete-with-completions-window'.  This breaks the previously
+available Embark integration.
+
+*** 'vcomplete-search-range' is no longer used in Emacs 29+.
+
 * 1.2.1
 
 ** Remove Embark integration.
diff --git a/README b/README
index 9f10289eb5..2691994ff1 100644
--- a/README
+++ b/README
@@ -1,7 +1,8 @@
 Vcomplete - Visual completions
 
-Vcomplete provides a minor mode enhancing the default completion
-list buffer, providing visual aids for selecting completions.
+Vcomplete provides a minor mode which highlights the completion at
+point the completion list buffer and (optionally) automatically
+updates it.
 
 Installation:
 
diff --git a/vcomplete.el b/vcomplete.el
index a450e01b7d..52c35171f5 100644
--- a/vcomplete.el
+++ b/vcomplete.el
@@ -26,8 +26,9 @@
 
 ;;; Commentary:
 
-;; Vcomplete provides a minor mode enhancing the default completion
-;; list buffer, providing visual aids for selecting completions.
+;; Vcomplete provides a minor mode which highlights the completion at
+;; point the completion list buffer and (optionally) automatically
+;; updates it.
 ;;
 ;; Usage:
 ;;
@@ -68,7 +69,22 @@
 
 ;;; Code:
 
-(eval-when-compile (require 'subr-x))
+(eval-when-compile
+  (require 'subr-x)
+  
+  ;; Avoid byte-compilation warnings.
+  (declare-function vcomplete--disable-completion-in-region nil)
+  (declare-function vcomplete--get-completions-window nil)
+  (declare-function vcomplete--highlight-completion-at-point nil)
+  (declare-function vcomplete--move-n-completions nil)
+  (declare-function vcomplete--setup-completions nil)
+  (declare-function vcomplete-choose-completion nil)
+  (declare-function vcomplete-next-completion nil)
+  (declare-function vcomplete-prev-completion nil)
+  (declare-function vcomplete-with-completions-window nil)
+  (defvar vcomplete--last-completion-overlay)
+  (defvar vcomplete-command-map)
+  (defvar vcomplete-search-range))
 
 ;;;; Customization:
 
@@ -95,53 +111,62 @@ Otherwise, operate according to `completion-auto-help'."
     vcomplete-choose-completion
     minibuffer-complete-and-exit
     minibuffer-force-complete-and-exit
+    minibuffer-next-completion
+    minibuffer-previous-completion
+    minibuffer-choose-completion
     completion-at-point
     choose-completion)
   "List of commands which shouldn't cause the `*Completions*' buffer to 
update."
   :link '(info-link "(Vcomplete)Completion commands")
   :type '(hook :tag "Commands")
   :risky t
-  :package-version '(vcomplete . 1.1))
+  :package-version '(vcomplete . 2.0))
 
-(defcustom vcomplete-search-range 'visible
-  "Range of search for a `*Completions*' window during completion.
+(defface vcomplete-highlight (if (and (boundp 'completions-highlight-face)
+                                      (facep completions-highlight-face))
+                                 `((t :inherit ,completions-highlight-face))
+                               '((t :inherit highlight)))
+  "Face for highlighting completions."
+  :package-version '(vcomplete . 2.0))
+
+(if (fboundp 'with-minibuffer-completions-window)
+    (defalias 'vcomplete-with-completions-window
+      #'with-minibuffer-completions-window)
+  (defcustom vcomplete-search-range 0
+    "Range of search for a `*Completions*' window during completion.
 - t means consider all windows on all frames.
 - `visible' means consider all windows on all visible frames.
 - 0 (the number zero) means consider all windows on all visible and
   iconified frames.
 - Any other value means consider all windows on the selected frame and
   no others."
-  :link '(info-link "(Vcomplete)Customization")
-  :type '(radio (const :tag "All windows on all frames" t)
-                (const :tag "All windows on all visible frames" visible)
-                (const
-                 :tag "All windows on all visible and iconified frames" 0)
-                (const
-                 :tag "All windows on the currently selected frame"
-                 nil))
-  :risky t
-  :package-version '(vcomplete . 1.2))
-
-(defface vcomplete-highlight '((t :inherit highlight))
-  "Face for highlighting completions."
-  :package-version '(vcomplete . 1.1))
+    :link '(info-link "(Vcomplete)Customization")
+    :type '(radio (const :tag "All windows on all frames" t)
+                  (const :tag "All windows on all visible frames" visible)
+                  (const
+                   :tag "All windows on all visible and iconified frames" 0)
+                  (const
+                   :tag "All windows on the currently selected frame"
+                   nil))
+    :risky t
+    :package-version '(vcomplete . 2.0))
 
 ;;;; Completion commands:
 
-(defun vcomplete--get-completions-window ()
-  "Return the window associated with the `*Completions*' buffer.
+  (defun vcomplete--get-completions-window ()
+    "Return the window associated with the `*Completions*' buffer.
 This function only searches the frames specified in `vcomplete-search-range'."
-  (get-buffer-window "*Completions*" vcomplete-search-range))
-
-(defmacro vcomplete-with-completions-window (&rest body)
-  "Evaluate BODY with the `*Completions*' window temporarily selected."
-  (declare (debug (&rest form)))
-  `(when-let ((window (vcomplete--get-completions-window)))
-     (with-selected-window window
-       (unless (derived-mode-p 'completion-list-mode)
-         (user-error
-          "The `*Completions*' buffer is set to an incorrect mode"))
-       ,@body)))
+    (get-buffer-window "*Completions*" vcomplete-search-range))
+
+  (defmacro vcomplete-with-completions-window (&rest body)
+    "Evaluate BODY with the `*Completions*' window temporarily selected."
+    (declare (debug (&rest form)))
+    `(when-let ((window (vcomplete--get-completions-window)))
+       (with-selected-window window
+         (unless (derived-mode-p 'completion-list-mode)
+           (user-error
+            "The `*Completions*' buffer is set to an incorrect mode"))
+         ,@body))))
 
 (defun vcomplete-current-completion (pos)
   "Get the completion candidate at POS.
@@ -167,52 +192,63 @@ isn't a completion list buffer."
                     (point-max)))
       `(,(buffer-substring-no-properties beg end) . (,beg . ,end)))))
 
-(defvar vcomplete--last-completion-overlay nil
-  "Last overlay created in the `*Completions*' buffer.")
-(put 'vcomplete--last-completion-overlay 'risky-local-variable t)
-
-(defun vcomplete--highlight-completion-at-point ()
-  "Highlight the completion at point in the `*Completions*' buffer."
-  (let ((cur (vcomplete-current-completion (point))))
-    (when vcomplete--last-completion-overlay
-      (delete-overlay vcomplete--last-completion-overlay))
-    (when-let ((pos (cdr cur)))
-      (overlay-put
-       (setq vcomplete--last-completion-overlay
-             (make-overlay (car pos) (cdr pos)))
-       'face 'vcomplete-highlight))))
-
-(defun vcomplete--move-n-completions (n)
-  "Move N completions in the `*Completions*' buffer."
-  (vcomplete-with-completions-window
-   (next-completion n)
-   (vcomplete--highlight-completion-at-point)))
-
-(defun vcomplete-next-completion (&optional n)
-  "Move to the next item in the `*Completions*' buffer.
+(if (boundp 'completions-highlight-face)
+    (defun vcomplete--move-n-completions (n)
+      "Move N completions in the `*Completions*' buffer."
+      (with-minibuffer-completions-window
+       (next-completion n)))
+  (defvar vcomplete--last-completion-overlay nil
+    "Last overlay created in the `*Completions*' buffer.")
+  (put 'vcomplete--last-completion-overlay 'risky-local-variable t)
+
+  (defun vcomplete--highlight-completion-at-point ()
+    "Highlight the completion at point in the `*Completions*' buffer."
+    (let ((cur (vcomplete-current-completion (point))))
+      (when vcomplete--last-completion-overlay
+        (delete-overlay vcomplete--last-completion-overlay))
+      (when-let ((pos (cdr cur)))
+        (overlay-put
+         (setq vcomplete--last-completion-overlay
+               (make-overlay (car pos) (cdr pos)))
+         'face 'vcomplete-highlight))))
+  
+  (defun vcomplete--move-n-completions (n)
+    "Move N completions in the `*Completions*' buffer."
+    (vcomplete-with-completions-window
+     (next-completion n)
+     (vcomplete--highlight-completion-at-point)))
+
+  (defun vcomplete-next-completion (&optional n)
+    "Move to the next item in the `*Completions*' buffer.
 With prefix argument N, move N items (negative N means move backward)."
-  (interactive "p")
-  (vcomplete--move-n-completions (or n 1)))
+    (interactive "p")
+    (vcomplete--move-n-completions (or n 1)))
 
-(defun vcomplete-prev-completion (&optional n)
-  "Move to the previous item in the `*Completions*' buffer.
+  (defun vcomplete-prev-completion (&optional n)
+    "Move to the previous item in the `*Completions*' buffer.
 With prefix argument N, move N items (negative N means move forward)."
-  (interactive "p")
-  (vcomplete--move-n-completions (- (or n 1))))
-
-(defun vcomplete-choose-completion ()
-  "Choose the completion at point in the `*Completions*' buffer."
-  (interactive)
-  (vcomplete-with-completions-window
-   (let ((completion-use-base-affixes t)) (choose-completion))))
-
-(defvar vcomplete-command-map
-  (let ((map (make-sparse-keymap)))
-    (define-key map [?\C-n] #'vcomplete-next-completion)
-    (define-key map [?\C-p] #'vcomplete-prev-completion)
-    (define-key map [?\C-\M-m] #'vcomplete-choose-completion)
-    map)
-  "Key map for completion commands.")
+    (interactive "p")
+    (vcomplete--move-n-completions (- (or n 1))))
+
+  (defun vcomplete-choose-completion ()
+    "Choose the completion at point in the `*Completions*' buffer."
+    (interactive)
+    (vcomplete-with-completions-window
+     (let ((completion-use-base-affixes t)) (choose-completion)))))
+
+(if (fboundp 'minibuffer-next-completion)
+    (defvar-keymap vcomplete-command-map
+      :doc "Key map for completion commands."
+      "C-n" #'minibuffer-next-completion
+      "C-p" #'minibuffer-previous-completion
+      "C-M-m" #'minibuffer-choose-completion)
+  (defvar vcomplete-command-map
+    (let ((map (make-sparse-keymap)))
+      (define-key map [?\C-n] #'vcomplete-next-completion)
+      (define-key map [?\C-p] #'vcomplete-prev-completion)
+      (define-key map [?\C-\M-m] #'vcomplete-choose-completion)
+      map)
+    "Key map for completion commands."))
 
 ;;;; Vcomplete mode:
 
@@ -234,22 +270,34 @@ With prefix argument N, move N items (negative N means 
move forward)."
 ;; since `after-change-functions' runs before the `*Completions*'
 ;; buffer is closed, so `completion-in-region-mode' can't be
 ;; immediately disabled through `vcomplete--update-in-region'.
-(defun vcomplete--disable-completion-in-region ()
-  "Stop completion in region when there is no visible `*Completions*' buffer."
-  (unless (vcomplete--get-completions-window)
-    (completion-in-region-mode -1)))
-
-(defun vcomplete--setup-completions ()
-  "Setup the `*Completions*' buffer for highlighting the completion at point."
-  (add-hook 'post-command-hook
-            #'vcomplete--highlight-completion-at-point nil t))
-
-(defun vcomplete--reset-completions ()
-  "Stop highlighting the completion at point in the `*Completions*' buffer."
-  (when-let ((buf (get-buffer "*Completions*")))
-    (with-current-buffer buf
-      (remove-hook 'post-command-hook
-                   #'vcomplete--highlight-completion-at-point t))))
+(if (fboundp 'with-minibuffer-completions-window)
+    (defun vcomplete--disable-completion-in-region ()
+      "Stop completion in region when there is no `*Completions*' window."
+      (unless (get-buffer-window "*Completions*" 0) ; Match `w-m-c-w'.
+        (completion-in-region-mode -1)))
+  (defun vcomplete--disable-completion-in-region ()
+    "Stop completion in region when there is no `*Completions*' window."
+    (unless (vcomplete--get-completions-window)
+      (completion-in-region-mode -1))))
+
+(if (boundp 'completions-highlight-face)
+    (defun vcomplete--setup-completions ()
+      "Force enable built-in highlighting in the `*Completions*' buffer."
+      (setq-local completions-highlight-face 'vcomplete-highlight
+                  cursor-face-highlight-nonselected-window t))
+  (defun vcomplete--setup-completions ()
+    "Setup the `*Completions*' buffer for highlighting the completion at 
point."
+    (add-hook 'post-command-hook
+              #'vcomplete--highlight-completion-at-point nil t)))
+
+(defun vcomplete--kill-completions ()
+  "Kill the `*Completions*' buffer and delete its window."
+  (when-let ((buf (get-buffer "*Completions*"))
+             ((with-current-buffer buf
+                (derived-mode-p 'completion-list-mode))))
+    (vcomplete-with-completions-window
+     (delete-window))
+    (kill-buffer buf)))
 
 (defun vcomplete--setup-minibuffer ()
   "Setup visual completions for the minibuffer."
@@ -298,7 +346,7 @@ The following bindings are available during completion:
         (add-hook 'minibuffer-setup-hook #'vcomplete--setup-minibuffer)
         (add-hook 'completion-in-region-mode-hook 
#'vcomplete--setup-in-region))
     (remove-hook 'completion-list-mode-hook #'vcomplete--setup-completions)
-    (vcomplete--reset-completions)
+    (vcomplete--kill-completions)
     (remove-hook 'minibuffer-setup-hook #'vcomplete--setup-minibuffer)
     (remove-hook 'completion-in-region-mode-hook 
#'vcomplete--setup-in-region)))
 
diff --git a/vcomplete.texi b/vcomplete.texi
index 364330987a..f11afc2341 100644
--- a/vcomplete.texi
+++ b/vcomplete.texi
@@ -41,8 +41,9 @@ General Public License for more details.
 @node Top
 @top Vcomplete User Manual
 
-Vcomplete provides a minor mode enhancing the default completion list
-buffer, providing visual aids for selecting completions.
+Vcomplete provides a minor mode which highlights the completion at
+point the completion list buffer and (optionally) automatically
+updates it.
 
 @noindent
 This manual is for Vcomplete version 1.2.1.
@@ -78,11 +79,11 @@ Customization
 @node Introduction
 @chapter Introduction
 
-Vcomplete provides a minor mode enhancing the default completion list
-buffer, providing visual aids for selecting completions. It's designed
-to build upon the default completion system, instead of replacing
-it. As such, it works both when completing in a minibuffer and in
-normal buffers.
+Vcomplete provides a minor mode which highlights the completion at
+point the completion list buffer and (optionally) automatically
+updates it. It builds upon the default completion system, instead of
+replacing it. As such, it works both when completing in a minibuffer
+and in normal buffers.
 
 @node Installation
 @chapter Installation
@@ -125,6 +126,9 @@ Install the package:
 @item @kbd{M-x package-install-file RET /path/to/clone/vcomplete-VERSION.tar 
RET}
 @end table
 
+An installable (with @code{package-install-file}) archive is built for
+every commit, available through <https://builds.sr.ht/~dsemy/vcomplete>.
+
 @node Usage
 @chapter Usage
 
@@ -133,36 +137,36 @@ It is recommended for @code{vcomplete-mode} to be enabled:
 @cindex vcomplete-mode
 @table @asis
 @item @kbd{M-x vcomplete-mode RET}
-You can also add @code{(vcomplete-mode)} to your init file, instead.
+You can also add @code{(vcomplete-mode)} to your init file, or enable
+it through the customize interface.
 @end table
 
 When @code{vcomplete-mode} is enabled, the @code{*Completions*} buffer
 appears and updates automatically (by default), and the completion at
-point in the @code{*Completions*} buffer is highlighted automatically.
+point in the @code{*Completions*} buffer is highlighted, even if
+@code{completions-highlight-face} (Emacs 29+) is nil.
 
-The following commands are also made available when completion is in
-progress:
+The following key bindings are also made available when completion is
+in progress:
 
 @kindex C-n
 @cindex vcomplete-next-completion
 @table @asis
 @item @kbd{C-n}
-Select the next displayed completion
-(@code{vcomplete-next-completion}).  This command moves point in the
-@code{*Completions*} buffer to the next available completion, and
-highlights it. This command may be used to advance multiple
-completions at a time with a prefix argument.
+Move point to the next displayed completion in the
+@code{*Completions*} window (@code{vcomplete-next-completion} or
+@code{minibuffer-next-completion} on Emacs 29+). This command may be
+used to move multiple completions at a time with a prefix argument.
 @end table
 
 @kindex C-p
 @cindex vcomplete-prev-completion
 @table @asis
 @item @kbd{C-p}
-Select the previous displayed completion
-(@code{vcomplete-prev-completion}).  This command moves point in the
-@code{*Completions*} buffer to the previous available completion, and
-highlights it. This command may be used to advance multiple
-completions at a time with a prefix argument.
+Move point to the next displayed completion in the
+@code{*Completions*} window (@code{vcomplete-prev-completion} or
+@code{minibuffer-previous-completion} on Emacs 29+). This command may
+be used to move multiple completions at a time with a prefix argument.
 @end table
 
 @kindex M-RET
@@ -170,13 +174,13 @@ completions at a time with a prefix argument.
 @table @asis
 @item @kbd{M-RET}
 Choose the currently highlighted completion in the
-@code{*Completions*} buffer (@code{vcomplete-choose-completion}).
+@code{*Completions*} window (@code{vcomplete-choose-completion}
+or @code{minibuffer-choose-completion} on Emacs 29+).
 @end table
 
 You may use these commands without enabling @code{vcomplete-mode}
-(although they won't be bound by default).
-@xref{Completion commands} for information regarding defining new
-commands.
+(although they won't be bound by default). @xref{Completion commands}
+for information regarding defining new commands.
 
 @node Customization
 @chapter Customization
@@ -190,13 +194,13 @@ be done through the customize interface:
 
 @defopt vcomplete-auto-update
 Whether the @code{*Completions*} buffer should open and update
-automatically. Non-nil means automatically open and
-update. Otherwise, operate according to
-@code{completion-auto-help}. By default, @code{t} is used. Note that
-with @code{completions-detailed} (introduced in Emacs 28) enabled, the
-@code{*Completions*} buffer takes much more time to display. This is
-also true for other ``annotation providers'' such as the Marginalia
-package. Consider disabling them or this option on slow computers.
+automatically. Non-nil means automatically open and update. Otherwise,
+operate according to @code{completion-auto-help}. By default, @code{t}
+is used. Note that with @code{completions-detailed} (introduced in
+Emacs 28) enabled, the @code{*Completions*} buffer takes much more
+time to display. This is also true for other ``annotation providers''
+such as the Marginalia package. Consider disabling them or this option
+on slow computers.
 @end defopt
 
 @defopt vcomplete-search-range
@@ -205,7 +209,10 @@ A value of @code{t} means consider all windows on all 
frames,
 @code{visible} means consider all windows on all visible frames,
 @code{0} (the number zero) means consider all windows on all visible
 and iconified frames and any other value means consider only the
-currently selected frame. By default, @code{visible} is used.
+currently selected frame. By default, @code{0} is used. In Emacs 29+
+this option is unavailable since built-in functions and macros are
+used, which don't respect its value. The built-in functions use the
+equivalent of setting this option to @code{0}.
 @end defopt
 
 @menu
@@ -226,27 +233,26 @@ to update.
 
 @defvar vcomplete-command-map
 Key map which holds key bindings to completion commands. This key map
-should be available whenever completion is initiated.
+should be available whenever completion is initiated when
+@code{vcomplete-mode} is enabled.
 @end defvar
 
 @defun vcomplete-current-completion pos
-Get the completion candidate at POS.
+Get the completion candidate at POS in the *Completions* buffer.
 The completion candidate is returned as a list of the form:
 @example
 (COMPLETION-STRING . (BEGINNING . END))
 @end example
-If no completion is found, this function returns nil. Note that this
-function throws an error when the major mode of the buffer from which
-it is called isn't derived from @code{completion-list-mode}.
+If no completion is found, this function returns nil.
 @end defun
 
-@defmac vcomplete-with-completions-buffer body...
-Evaluate BODY with the @code{*Completions*} buffer temporarily
-current.  While evaluating BODY, BUFFER and WINDOW are locally bound
-to the @code{*Completions*} buffer and window respectively. This macro
-can be used to easily manipulate or access the contents of the
-@code{*Completions*} buffer. If there is no @code{*Completions*}
-buffer or no window displaying it BODY isn't executed.
+@defmac vcomplete-with-completions-window body...
+Evaluate BODY with the @code{*Completions*} window temporarily
+selected. This macro can be used to easily manipulate or access the
+contents of the @code{*Completions*} buffer. If there is no
+@code{*Completions*} buffer or no window displaying it BODY isn't
+executed. On Emacs 29+, this macro is an alias to the built-in
+@code{with-minibuffer-completions-window} macro.
 @end defmac
 
 @node Keystroke Index