[elpa] externals/mct ebffb0642b 1/2: Add mct-avy.el and document it in the manual

[ELPA Syncer]

branch: externals/mct
commit ebffb0642bf8bb837e058618b0c876761c5eb1d4
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Add mct-avy.el and document it in the manual
---
 README.org            | 130 ++++++++++++++++++++------------------------------
 extensions/mct-avy.el |  85 +++++++++++++++++++++++++++++++++
 2 files changed, 137 insertions(+), 78 deletions(-)

diff --git a/README.org b/README.org
index 4872c8ddc5..f68d7262d1 100644
--- a/README.org
+++ b/README.org
@@ -975,6 +975,58 @@ The MCT code repository contains an =extensions= 
directory.  Any file
 found there is considered highly experimental.  The target audience is
 developers or users who wish to help find bugs.
 
+** MCT and Avy
+:PROPERTIES:
+:CUSTOM_ID: h:18a2a223-8544-4294-b847-012c99003de4
+:END:
+#+cindex: Quick selection with Avy
+
+[ Part of {{{development-version}}} ]
+
+The MCT =extensions= directory contains the =mct-avy.el= file.  It
+integrates MCT with the =avy= package to choose completion candidates
+using the latter's mode of interaction.  The commands it defines are:
+
++ ~mct-avy-choose-completion-exit~.
++ ~mct-avy-choose-completion-dwim~.
++ ~mct-avy-choose-completion-jump~.
++ ~mct-avy-region-choose-completion~.
+
+Their respective doc strings describe their functionality.
+
+=mct-avy.el= does not bind any keys.  Choose your own with something
+like this:
+
+#+begin_src emacs-lisp
+(dolist (map (list mct-minibuffer-local-completion-map
+                   mct-minibuffer-completion-list-map))
+  (define-key map (kbd "C-;") #'mct-avy-choose-completion-exit)
+  (define-key map (kbd "M-;") #'mct-avy-choose-completion-dwim))
+
+;; If you are using `mct-region-mode':
+(dolist (map (list mct-region-completion-list-map
+                   mct-region-buffer-map))
+  (define-key map (kbd "C-;") #'mct-avy-region-choose-completion))
+#+end_src
+
+At the heart of the package is the function ~mct-avy-choose~ which
+provides the minimal necessary glue code.  Use it to extend the
+functionality on offer.  For example, here is how to call ~embark-act~
+on the candidate (requires the =embark= package):
+
+#+begin_src emacs-lisp
+(defun my-mct-avy-embark-act ()
+  "Use Avy to run `embark-act' on candidate."
+  (interactive)
+  (mct-avy--choose #'embark-act))
+#+end_src
+
+=mct-avy.el= is inspired by Omar Antolín Camarena's
+=avy-embark-collect.el=.  The ~mct-avy-choose~ function borrows code
+and/or ideas from that libary: <https://github.com/oantolin/embark/>.
+
+[[#h:03227254-d467-4147-b8cf-2fe05a2e279b][Third-party extensions]].
+
 * Known issues and workarounds
 :PROPERTIES:
 :CUSTOM_ID: h:acfb63f4-c2ae-46ff-a840-9c9a6350e567
@@ -1158,84 +1210,6 @@ not be part of =mct.el=.  Use this in your init file 
instead:
 (advice-add #'completing-read-multiple :filter-args #'my-crm-indicator)
 #+end_src
 
-** Select completion candidate with Avy
-:PROPERTIES:
-:CUSTOM_ID: h:18a2a223-8544-4294-b847-012c99003de4
-:END:
-#+cindex: Quick selection with Avy
-
-The =avy= package by Oleh Krehel can be used to quickly select a candidate
-from a visible =*Completions*= buffer.  In the following example, we
-activate it with the =C-.= key.
-
-#+begin_src emacs-lisp
-;; Adapted from Omar Antolín Camarena's `avy-embark-collect.el'.
-(defun my-avy--choose (pt)
-  "Choose completion at PT."
-  (goto-char pt)
-  (mct-choose-completion-exit))
-
-(defun my-avy-completions-select ()
-  "Choose completion and exit using Avy."
-  (interactive)
-  (when-let ((window (mct--get-completion-window)))
-    (with-selected-window window
-      (avy-with avy-completion
-        (let ((avy-action 'mct-avy--choose))
-          (avy-process
-           (save-excursion
-             (let (completions)
-               (goto-char (mct--first-completion-point))
-               (while (not (eobp))
-                 (push (point) completions)
-                 (next-completion 1))
-               (nreverse completions)))))))))
-
-(dolist (map (list mct-minibuffer-local-completion-map
-                   mct-minibuffer-completion-list-map
-                   mct-region-completion-list-map
-                   mct-region-buffer-map))
-  (define-key map (kbd "C-.") #'my-avy-completions-select))
-#+end_src
-
-If you are declaring =mct= before =avy= in your init file, then the above
-can be wrapped in ~with-eval-after-load~, like this:
-
-#+begin_src emacs-lisp
-(require 'mct)
-
-;; more mct code here
-
-(with-eval-after-load 'avy
-  ;; Adapted from Omar Antolín Camarena's `avy-embark-collect.el'.
-  (defun my-avy--choose (pt)
-    "Choose completion at PT."
-    (goto-char pt)
-    (mct-choose-completion-exit))
-
-  (defun my-avy-completions-select ()
-    "Choose completion and exit using Avy."
-    (interactive)
-    (when-let ((window (mct--get-completion-window)))
-      (with-selected-window window
-        (avy-with avy-completion
-          (let ((avy-action 'mct-avy--choose))
-            (avy-process
-             (save-excursion
-               (let (completions)
-                 (goto-char (mct--first-completion-point))
-                 (while (not (eobp))
-                   (push (point) completions)
-                   (next-completion 1))
-                 (nreverse completions)))))))))
-
-  (dolist (map (list mct-minibuffer-local-completion-map
-                     mct-minibuffer-completion-list-map
-                     mct-region-completion-list-map
-                     mct-region-buffer-map))
-    (define-key map (kbd "C-.") #'my-avy-completions-select)))
-#+end_src
-
 ** Ido-style navigation through directories
 :PROPERTIES:
 :CUSTOM_ID: h:9a6746dd-0be9-4e29-ac40-0af9612d05a2
diff --git a/extensions/mct-avy.el b/extensions/mct-avy.el
new file mode 100644
index 0000000000..8cbe1af3ec
--- /dev/null
+++ b/extensions/mct-avy.el
@@ -0,0 +1,85 @@
+;;; mct-avy.el --- MCT integration with Avy -*- lexical-binding: t -*-
+
+;; Copyright (C) 2022  Free Software Foundation, Inc.
+
+;; Author: Protesilaos Stavrou <info@protesilaos.com>
+;; URL: https://gitlab.com/protesilaos/mct
+;; Version: 0.5.0
+;; Package-Requires: ((emacs "27.1") (avy "0.5") (mct "0.5"))
+
+;; This file is NOT part of GNU Emacs.
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or (at
+;; your option) any later version.
+;;
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+;;
+;; MCT extension which provides the means to select a completion
+;; candidate with the `avy' package's mode of interaction.
+;;
+;; Inspired by Omar Antolín Camarena's `avy-embark-collect.el'.  The
+;; `mct-avy-choose' function borrows code or ideas from that library:
+;; <https://github.com/oantolin/embark/>.
+
+;;; Code:
+
+;;;; General utilities
+
+(require 'mct)
+(require 'avy)
+
+(defun mct-avy-choose (&optional fn)
+  "Use Avy to go to completion candidate and optionally run FN."
+  (cond
+   ((mct--get-completion-window)
+    (mct-switch-to-completions-top)
+    (goto-char
+     (avy-process
+      (save-excursion
+        (let (completions)
+          (goto-char (mct--last-completion-point))
+          (while (not (bobp))
+            (push (point) completions)
+            (previous-completion 1))
+          completions))))
+    (when fn (funcall fn)))
+   (t (user-error "No Completions' buffer available"))))
+
+;;;###autoload
+(defun mct-avy-choose-completion-exit ()
+  "Use Avy to run `mct-choose-completion-exit' on candidate."
+  (interactive)
+  (mct-avy-choose #'mct-choose-completion-exit))
+
+;;;###autoload
+(defun mct-avy-choose-completion-dwim ()
+  "Use Avy to run `mct-choose-completion-dwim' on candidate."
+  (interactive)
+  (mct-avy-choose #'mct-choose-completion-dwim))
+
+;;;###autoload
+(defun mct-avy-choose-completion-jump ()
+  "Use Avy to jump to the selected candidate."
+  (interactive)
+  (mct-avy-choose))
+
+;;;###autoload
+(defun mct-avy-region-choose-completion ()
+  "Use Avy to run `choose-completion' on candidate.
+Intended for use with the MCT region mode for in-buffer
+completion where the minibuffer is not active."
+  (interactive)
+  (mct-avy-choose #'choose-completion))
+
+(provide 'mct-avy)
+;;; mct-avy.el ends here