[elpa] externals/mct 2413746369 11/64: Merge 'main' into experiment-completion-in-region

[ELPA Syncer]

branch: externals/mct
commit 24137463699b0cb48d3ee9bba3028d668095effa
Merge: 6222731289 9d204c6f70
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Merge 'main' into experiment-completion-in-region
---
 README.org | 116 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 mct.el     |  71 +++++++++++++++++--------------------
 2 files changed, 144 insertions(+), 43 deletions(-)

diff --git a/README.org b/README.org
index 469a178202..5c8ef67e56 100644
--- a/README.org
+++ b/README.org
@@ -275,6 +275,14 @@ There are several ways to select a completion candidate.
    completion candidate, so it retains its behaviour (as explained right
    above).
 
+   #+findex: mct-focus-minibuffer
+   Sometimes there is a need to switch to the minibuffer without
+   selecting the candidate at point, such as to retype some part of the
+   input.  In those cases, type =e= in the completions' buffer to move to
+   the minibuffer.  The command is called ~mct-focus-minibuffer~, which
+   can also be assigned to the global keymap, though MCT leaves such a
+   decision up to the user (same for ~mct-focus-mini-or-completions~).
+
    #+findex: mct-choose-completion-number
 5. Select a candidate by its line number by typing =M-g M-g= in either the
    minibuffer or the =*Completions*= buffer.  This calls the command
@@ -530,6 +538,84 @@ If you want to edit any key bindings, do it in these 
keymaps, not in
 those they extend and override (the names of the original ones are the
 same as above, minus the =mct-= prefix).
 
+* User-level tweaks or custom code
+:PROPERTIES:
+:CUSTOM_ID: h:2630a7a3-1b11-4e9d-8282-0ea3bf9e2a5b
+:END:
+#+cindex: Custom tweaks or extensions
+
+In this section we cover custom code that builds on what MCT offers.
+
+** MCT in the current or the other window
+:PROPERTIES:
+:CUSTOM_ID: h:891c7841-9cdc-42df-bba9-45f7409b807c
+:END:
+
+Over at the [[https://git.sr.ht/~abcdw/rde][rde project]], Andrew Tropin 
configures MCT to display the
+Completions' buffer in either of two places:
+
++ Current window ::  This is the default behaviour.  It means that
+  completions are presented where the user is already focused on,
+  instead of the bottom of the display or some side window.
+
++ Other window :: The least recently used window when the command that
+  performs completion matches certain categories whose candidates are
+  best shown next to the current window/context.  For example, Imenu
+  (and extensions like ~consult-imenu~) creates a dynamically generated
+  index of "points of interest" in the current buffer, so it is useful
+  to have this displayed in the other window.
+
+Implementation details and particular preferences aside, this is a great
+example of using the various ~display-buffer~ functions to control the
+placement of the =*Completions*= buffer.
+
+#+begin_src emacs-lisp
+(defvar rde-completion-categories-other-window
+  '(imenu)
+  "Completion categories that has to be in other window than
+current, otherwise preview functionallity will fail the party.")
+
+(defvar rde-completion-categories-not-show-candidates-on-setup
+  '(command variable function)
+  "Completion categories that has to be in other window than
+current, otherwise preview functionallity will fail the party.")
+
+(defun rde-display-mct-buffer-pop-up-if-apropriate (buffer alist)
+  "Call `display-buffer-pop-up-window' if the completion category
+one of `rde-completion-categories-other-window', it will make
+sure that we don't use same window for completions, which should
+be in separate window."
+  (if (memq (mct--completion-category)
+            rde-completion-categories-other-window)
+      (display-buffer-pop-up-window buffer alist)
+    nil))
+
+(defun rde-display-mct-buffer-apropriate-window (buffer alist)
+  "Displays completion buffer in the same window, where completion
+was initiated (most recent one), but in case, when compeltion
+buffer should be displayed in other window use least recent one."
+  (let* ((window (if (memq (mct--completion-category)
+                           rde-completion-categories-other-window)
+                     (get-lru-window (selected-frame) nil nil)
+                   (get-mru-window (selected-frame) nil nil))))
+    (window--display-buffer buffer window 'reuse alist)))
+
+(setq mct-display-buffer-action
+      (quote ((display-buffer-reuse-window
+               rde-display-mct-buffer-pop-up-if-apropriate
+               rde-display-mct-buffer-apropriate-window))))
+
+(defun rde-mct-show-completions ()
+  "Instantly shows completion candidates for categories listed in
+`rde-completion-categories-show-candidates-on-setup'."
+  (unless (memq (mct--completion-category)
+                rde-completion-categories-not-show-candidates-on-setup)
+    (setq-local mct-minimum-input 0)
+    (mct--live-completions)))
+
+(add-hook 'minibuffer-setup-hook 'rde-mct-show-completions)
+#+end_src
+
 * Extensions
 :PROPERTIES:
 :CUSTOM_ID: h:03227254-d467-4147-b8cf-2fe05a2e279b
@@ -555,6 +641,27 @@ these exceptionally well-crafted extras:
   patterns (regexp, flex, initialism, etc.) regardless of the order they
   appear in.
 
++ 
[[https://github.com/iyefrat/all-the-icons-completion][all-the-icons-completion]]
 by Itai Y. Efrat :: Glue code that adds icons
+  from the =all-the-icons= package to the =*Completions*= buffer.  It can
+  make things prettier and/or more informative, while it can also be
+  combined with Marginalia.
+
+MCT does not support the use-case of ~completion-in-region~.  This is the
+kind of completion session that does not involve the minibuffer and is
+instead about in-buffer text expansion.  Consider these packages:
+
++ [[https://github.com/minad/corfu/][Corfu]] by Daniel Mendler :: An interface 
for the ~completion-in-region~
+  which uses a child frame (basically a pop-up) at the position of the
+  cursor to display candidates.  As with all of Daniel's packages, Corfu
+  aims for a clean implementation that does the right thing by being
+  consistent with core Emacs mechanisms.
+
++ [[https://github.com/minad/cape][Cape]] also by Daniel :: Additional 
~completion-at-point-functions~
+  (CAPFs) that extend those of core Emacs.  These backends can be used
+  by Corfu, though their modular nature makes them suitable for use by
+  other compliant packages (e.g. a potential minimalist package that is
+  cleanly designed like Corfu but has a different interface).
+
 ** Enable Consult previews
 :PROPERTIES:
 :CUSTOM_ID: h:85268cb1-9d49-452c-ba5f-c9215d4b8b62
@@ -664,11 +771,12 @@ MCT is meant to be a collective effort.  Every bit of 
help matters.
 + Author/maintainer :: Protesilaos Stavrou.
 
 + Contributions to code or documentation :: Daniel Mendler, James Norman
-  Vladimir Cash, José Antonio Ortega Ruiz, Philip Kaludercic.
+  Vladimir Cash, José Antonio Ortega Ruiz, Juri Linkov, Philip
+  Kaludercic.
 
-+ Ideas and user feedback :: Case Duckworth, Jonathan Irving, José
-  Antonio Ortega Ruiz, Kostadin Ninev, Manuel Uberti, Philip Kaludercic,
-  Theodor Thornhill.
++ Ideas and user feedback :: Benjamin (@zealotrush), Case Duckworth,
+  Jonathan Irving, José Antonio Ortega Ruiz, Kostadin Ninev, Manuel
+  Uberti, Philip Kaludercic, Theodor Thornhill.
 
 + Inspiration for certain features :: =icomplete.el= (built-in---multiple
   authors), Daniel Mendler (=vertico=), Omar Antolín Camarena (=embark=,
diff --git a/mct.el b/mct.el
index c06d4a496b..df12951050 100644
--- a/mct.el
+++ b/mct.el
@@ -231,7 +231,7 @@ See `completions-format' for possible values."
                                (goto-char prev))))))
       (put-text-property (point-min) (point) 'invisible t))))
 
-(defun mct--fit-completions-window ()
+(defun mct--fit-completions-window (&rest _args)
   "Fit Completions' buffer to its window."
   (when-let ((window (mct--get-completion-window)))
     (with-current-buffer (window-buffer window)
@@ -277,16 +277,20 @@ Meant to be added to `after-change-functions'."
   (when (window-live-p (mct--get-completion-window))
     (mct--live-completions-timer)))
 
+(defun mct--this-command ()
+  "Return this command."
+  (or (bound-and-true-p current-minibuffer-command) this-command))
+
 (defun mct--setup-live-completions ()
   "Set up the completions' buffer."
   (cond
-   ((memq this-command mct-completion-passlist)
+   ((memq (mct--this-command) mct-completion-passlist)
     (setq-local mct-minimum-input 0)
     (setq-local mct-live-update-delay 0)
     (mct--show-completions)
     (add-hook 'after-change-functions #'mct--live-completions nil t))
    ((null mct-live-completion))
-   ((not (memq this-command mct-completion-blocklist))
+   ((not (memq (mct--this-command) mct-completion-blocklist))
     (if (eq mct-live-completion 'visible)
         (add-hook 'after-change-functions 
#'mct--live-completions-visible-timer nil t)
       (add-hook 'after-change-functions #'mct--live-completions-timer nil 
t)))))
@@ -300,18 +304,11 @@ Meant to be added to `after-change-functions'."
               (buf (window-buffer win)))
       (buffer-local-value 'mct--active buf)))
 
-;; FIXME 2021-12-03: The `completion-in-region-mode' is not sufficient.
-;; We should also be testing if the user has opted in to using mct for
-;; such a purpose.  Maybe adapting `mct--active-p' is in order.
-(defun mct--region-or-minibuffer-active-p ()
-  "Test is mct is active for the current completion method."
-  (or completion-in-region-mode (mct--active-p)))
-
 (defun mct--display-completion-list-advice (&rest app)
   "Prepare advice around `display-completion-list'.
 Apply APP by first let binding the `completions-format' to
-`mct-completions-format', when appropriate."
-  (if (mct--region-or-minibuffer-active-p)
+`mct-completions-format'."
+  (if (mct--active-p)
       (let ((completions-format mct-completions-format))
         (apply app))
     (apply app)))
@@ -565,7 +562,7 @@ a `one-column' value."
 (defun mct--bottom-of-completions-p (arg)
   "Test if point is at the notional bottom of the Completions.
 ARG is a numeric argument for `next-completion', as described in
-`mct-next-completion-or-switch'."
+`mct-next-completion-or-mini'."
   (or (eobp)
       (mct--completions-line-boundary (mct--last-completion-point))
       (= (save-excursion (next-completion arg) (point)) (point-max))
@@ -595,7 +592,7 @@ minibuffer."
   (interactive "p" mct-mode)
   (cond
    ((mct--bottom-of-completions-p (or arg 1))
-    (mct--focus-buf-or-mini))
+    (mct-focus-minibuffer))
    (t
     (if (not (mct--one-column-p))
         ;; Retaining the column number ensures that things work
@@ -620,12 +617,12 @@ minibuffer."
 (defun mct--top-of-completions-p (arg)
   "Test if point is at the notional top of the Completions.
 ARG is a numeric argument for `previous-completion', as described in
-`mct-previous-completion-or-switch'."
+`mct-previous-completion-or-mini'."
   (or (bobp)
       (mct--completions-line-boundary (mct--first-completion-point))
       (= (save-excursion (previous-completion arg) (point)) (point-min))))
 
-(defun mct-previous-completion-or-switch (&optional arg)
+(defun mct-previous-completion-or-mini (&optional arg)
   "Move to the next completion or switch to the minibuffer.
 This performs a regular motion for optional ARG lines, but when
 point can no longer move in that direction it switches to the
@@ -633,7 +630,7 @@ minibuffer."
   (interactive "p" mct-mode)
   (cond
    ((mct--top-of-completions-p (if (natnump arg) arg 1))
-    (mct--focus-buf-or-mini))
+    (mct-focus-minibuffer))
    ((if (not (mct--one-column-p))
         ;; Retaining the column number ensures that things work
         ;; intuitively in a grid view.
@@ -691,11 +688,11 @@ If ARG is supplied, move that many completion groups at a 
time."
 (defun mct-choose-completion-exit ()
   "Run `choose-completion' in the Completions buffer and exit."
   (interactive nil mct-mode)
-  (when-let* ((window (mct--get-completion-window))
-              (buffer (window-buffer)))
-    (with-current-buffer buffer
-      (choose-completion))
-    (when (active-minibuffer-window)
+  (when (active-minibuffer-window)
+    (when-let* ((window (mct--get-completion-window))
+                (buffer (window-buffer)))
+      (with-current-buffer buffer
+        (choose-completion))
       (minibuffer-force-complete-and-exit))))
 
 (defun mct-choose-completion-no-exit ()
@@ -861,13 +858,6 @@ If in a completions' buffer and unless the region is 
active, run
 If the region is active, deactivate it.  A second invocation of
 this command is then required to abort the session."
   (interactive nil mct-mode)
-  ;; TODO 2021-12-03: We want a "now doing completion in region"
-  ;; predicate that would yield the right result while we are inside the
-  ;; Completions.  When t we want to `bury-buffer' the Completions.
-  ;;
-  ;; The use-case for this is that you enter completion-in-region, cycle
-  ;; to the completions and then realise you made a mistake for C-g
-  ;; should do the right thing and take you back to the prior state.
   (when (derived-mode-p 'completion-list-mode)
     (if (use-region-p)
         (keyboard-quit)
@@ -928,7 +918,7 @@ Apply APP while inhibiting modification hooks."
            mct-remove-shadowed-file-names
            (eq (mct--completion-category) 'file)
            rfn-eshadow-overlay (overlay-buffer rfn-eshadow-overlay)
-           (eq this-command 'self-insert-command)
+           (eq (mct--this-command) 'self-insert-command)
            (= saved-point (point-max))
            (or (>= (- (point) (overlay-end rfn-eshadow-overlay)) 2)
                (eq ?/ (char-before (- (point) 2)))))
@@ -1006,12 +996,13 @@ region.")
     (define-key map (kbd "M-v") #'scroll-down-command)
     (define-key map [remap keyboard-quit] #'mct-keyboard-quit-dwim)
     (define-key map [remap goto-line] #'mct-choose-completion-number)
-    (define-key map [remap next-line] #'mct-next-completion-or-switch)
-    (define-key map (kbd "n") #'mct-next-completion-or-switch)
-    (define-key map [remap previous-line] #'mct-previous-completion-or-switch)
-    (define-key map (kbd "p") #'mct-previous-completion-or-switch)
+    (define-key map [remap next-line] #'mct-next-completion-or-mini)
+    (define-key map (kbd "n") #'mct-next-completion-or-mini)
+    (define-key map [remap previous-line] #'mct-previous-completion-or-mini)
     (define-key map (kbd "M-p") #'mct-previous-completion-group)
     (define-key map (kbd "M-n") #'mct-next-completion-group)
+    (define-key map (kbd "p") #'mct-previous-completion-or-mini)
+    (define-key map (kbd "e") #'mct-focus-minibuffer)
     (define-key map (kbd "M-e") #'mct-edit-completion)
     (define-key map (kbd "<tab>") #'mct-choose-completion-no-exit)
     (define-key map (kbd "<return>") #'mct-choose-completion-exit)
@@ -1057,8 +1048,8 @@ region.")
                            (current-local-map)))))
 
 (defun mct--setup-completion-list ()
-  "Set up Mct for the completion-list."
-  (when (mct--region-or-minibuffer-active-p)
+  "Set up the completion-list for Mct."
+  (when (mct--active-p)
     (setq-local completion-show-help nil)
     (mct--setup-clean-completions)
     (mct--setup-appearance)
@@ -1073,11 +1064,11 @@ region.")
 (declare-function minibuf-eldef-setup-minibuffer "minibuf-eldef")
 
 ;;;###autoload
-(define-minor-mode mct-minibuffer-mode
-  "Set up interactivity over the default minibuffer completion."
+(define-minor-mode mct-mode
+  "Set up opinionated default completion UI."
   :global t
   :group 'mct
-  (if mct-minibuffer-mode
+  (if mct-mode
       (progn
         (add-hook 'completion-list-mode-hook #'mct--setup-completion-list)
         (dolist (fn '(exit-minibuffer
@@ -1090,6 +1081,7 @@ region.")
         (advice-add #'completing-read-multiple :around 
#'mct--completing-read-advice)
         (advice-add #'completing-read-multiple :filter-args 
#'mct--crm-indicator)
         (advice-add #'display-completion-list :around 
#'mct--display-completion-list-advice)
+        (advice-add #'minibuffer-completion-help :after 
#'mct--fit-completions-window)
         (advice-add #'minibuffer-message :around #'mct--honor-inhibit-message)
         (advice-add #'minibuf-eldef-setup-minibuffer :around 
#'mct--stealthily))
     (remove-hook 'completion-list-mode-hook #'mct--setup-completion-list)
@@ -1103,6 +1095,7 @@ region.")
     (advice-remove #'completing-read-multiple #'mct--completing-read-advice)
     (advice-remove #'completing-read-multiple #'mct--crm-indicator)
     (advice-remove #'display-completion-list 
#'mct--display-completion-list-advice)
+    (advice-remove #'minibuffer-completion-help #'mct--fit-completions-window)
     (advice-remove #'minibuffer-message #'mct--honor-inhibit-message)
     (advice-remove #'minibuf-eldef-setup-minibuffer #'mct--stealthily)))