emacs: add rul-completion to literate config

2 files changed, 163 insertions, 36 deletions

diff --git a/.emacs.d/rul-emacs.org b/.emacs.d/rul-emacs.org
index 4cb505c..40cb281 100644
--- a/.emacs.d/rul-emacs.org
+++ b/.emacs.d/rul-emacs.org
@@ -350,3 +350,154 @@ the potential to obsolete =hydra=, so I'll have to revisit that code.
 
 (provide 'rul-bindings)
 #+end_src
+
+** The =completions= module
+This module contains code pertaining to completion and the minibuffer.
+
+#+begin_src emacs-lisp :tangle "rul-lisp/packages/rul-completion.el"
+(use-package orderless :ensure t)
+
+(setq completion-styles '(basic substring initials orderless))
+(setq completion-category-overrides
+      '(
+        (file (styles . (basic partial-completion orderless)))
+        (project-file (styles . (flex basic substring partial-completion orderless)))
+        ))
+
+(setq completion-ignore-case t)
+#+end_src
+
+The =vertico= package provides a vertical completion UI based on the default completion
+system.
+
+#+begin_src emacs-lisp :tangle "rul-lisp/packages/rul-completion.el"
+;; Enable vertico
+(use-package vertico
+  :ensure t
+  :init
+  (vertico-mode)
+
+  :config
+  (add-hook 'rfn-eshadow-update-overlay-hook #'vertico-directory-tidy))
+#+end_src
+
+The =marginalia= package annotates the completion candidates with useful contextual
+information.
+
+#+begin_src emacs-lisp :tangle "rul-lisp/packages/rul-completion.el"
+;; Enable rich annotations using the Marginalia package
+(use-package marginalia
+  :ensure t
+  :bind (:map minibuffer-local-map
+         ("M-A" . marginalia-cycle))
+  :init
+  (marginalia-mode))
+#+end_src
+
+The =consult= package replaces most of Emacs core functions with
+completion-friendly alternatives that integrates well with =vertico= and
+=marginalia=.
+
+#+begin_src emacs-lisp :tangle "rul-lisp/packages/rul-completion.el"
+(use-package consult
+  :ensure t
+  :bind (;; C-c bindings in `mode-specific-map'
+         ("C-c M-x" . consult-mode-command)
+         ("C-c h" . consult-history)
+         ("C-c k" . consult-kmacro)
+         ("C-c m" . consult-man)
+         ("C-c i" . consult-info)
+         ([remap Info-search] . consult-info)
+
+         ;; C-x bindings in `ctl-x-map'
+         ("C-x M-:" . consult-complex-command)     ;; orig. repeat-complex-command
+         ("C-x b" . consult-buffer)                ;; orig. switch-to-buffer
+         ("C-x 4 b" . consult-buffer-other-window) ;; orig. switch-to-buffer-other-window
+         ("C-x 5 b" . consult-buffer-other-frame)  ;; orig. switch-to-buffer-other-frame
+         ("C-x r b" . consult-bookmark)            ;; orig. bookmark-jump
+         ("C-x p b" . consult-project-buffer)      ;; orig. project-switch-to-buffer
+
+         ;; Custom M-# bindings for fast register access
+         ("M-#" . consult-register-load)
+         ("M-'" . consult-register-store)          ;; orig. abbrev-prefix-mark (unrelated)
+         ("C-M-#" . consult-register)
+
+         ;; Other custom bindings
+         ("M-y" . consult-yank-pop)                ;; orig. yank-pop
+
+         ;; M-g bindings in `goto-map'
+         ("M-g e" . consult-compile-error)
+         ("M-g f" . consult-flymake)               ;; Alternative: consult-flycheck
+         ("M-g g" . consult-goto-line)             ;; orig. goto-line
+         ("M-g M-g" . consult-goto-line)           ;; orig. goto-line
+         ("M-g o" . consult-outline)               ;; Alternative: consult-org-heading
+         ("M-g m" . consult-mark)
+         ("M-g k" . consult-global-mark)
+         ("M-g i" . consult-imenu)
+         ("M-g I" . consult-imenu-multi)
+
+         ;; M-s bindings in `search-map'
+         ("M-s d" . consult-find)
+         ("M-s D" . consult-locate)
+         ("M-s g" . consult-grep)
+         ("M-s G" . consult-git-grep)
+         ("M-s r" . consult-ripgrep)
+         ("M-s l" . consult-line)
+         ("M-s L" . consult-line-multi)
+         ("M-s k" . consult-keep-lines)
+         ("M-s u" . consult-focus-lines)
+
+         ;; Isearch integration
+         ("M-s e" . consult-isearch-history)
+
+         :map isearch-mode-map
+         ("M-e" . consult-isearch-history)         ;; orig. isearch-edit-string
+         ("M-s e" . consult-isearch-history)       ;; orig. isearch-edit-string
+         ("M-s l" . consult-line)                  ;; needed by consult-line to detect isearch
+         ("M-s L" . consult-line-multi)            ;; needed by consult-line to detect isearch
+
+         ;; Minibuffer history
+         :map minibuffer-local-map
+         ("M-s" . consult-history)                 ;; orig. next-matching-history-element
+         ("M-r" . consult-history))                ;; orig. previous-matching-history-element
+
+  :init
+  (setq xref-show-xrefs-function #'consult-xref)
+  (setq xref-show-definitions-function #'consult-xref)
+  (add-hook 'completion-list-mode-hook #'consult-preview-at-point-mode)
+
+  :config
+  (setq consult-preview-key 'any)
+  (setq consult-narrow-key "<")
+)
+#+end_src
+
+The next piece of code corresponds to =embark=, a package that enables
+context-specific actions in the minibuffer, or common buffers.
+
+#+begin_src emacs-lisp :tangle "rul-lisp/packages/rul-completion.el"
+(use-package embark
+  :ensure t
+
+  :bind
+  (("C-." . embark-act)         ;; pick some comfortable binding
+   ("M-." . embark-dwim)        ;; good alternative: M-.
+   ("C-h B" . embark-bindings)) ;; alternative for `describe-bindings'
+
+  :init
+  (setq prefix-help-command #'embark-prefix-help-command)
+
+  :config
+  ;; Hide the mode line of the Embark live/completions buffers
+  (add-to-list 'display-buffer-alist
+               '("\\`\\*Embark Collect \\(Live\\|Completions\\)\\*"
+                 nil
+                 (window-parameters (mode-line-format . none)))))
+
+(use-package embark-consult
+  :ensure t
+  :hook
+  (embark-collect-mode . consult-preview-at-point-mode))
+
+(provide 'rul-completion)
+#+end_src
diff --git a/.emacs.d/rul-lisp/packages/rul-completion.el b/.emacs.d/rul-lisp/packages/rul-completion.el
index 2b3afa1..3412354 100644
--- a/.emacs.d/rul-lisp/packages/rul-completion.el
+++ b/.emacs.d/rul-lisp/packages/rul-completion.el
@@ -1,5 +1,14 @@
 (use-package orderless :ensure t)
 
+(setq completion-styles '(basic substring initials orderless))
+(setq completion-category-overrides
+      '(
+        (file (styles . (basic partial-completion orderless)))
+        (project-file (styles . (flex basic substring partial-completion orderless)))
+        ))
+
+(setq completion-ignore-case t)
+
 ;; Enable vertico
 (use-package vertico
   :ensure t
@@ -7,50 +16,18 @@
   (vertico-mode)
 
   :config
-  (add-hook 'rfn-eshadow-update-overlay-hook #'vertico-directory-tidy)
-
-  ;; Different scroll margin
-  ;; (setq vertico-scroll-margin 0)
-
-  ;; Show more candidates
-  ;; (setq vertico-count 20)
-
-  ;; Grow and shrink the Vertico minibuffer
-  ;; (setq vertico-resize t)
-
-  ;; Optionally enable cycling for `vertico-next' and `vertico-previous'.
-  ;; (setq vertico-cycle t)
-  )
+  (add-hook 'rfn-eshadow-update-overlay-hook #'vertico-directory-tidy))
 
 ;; Enable rich annotations using the Marginalia package
 (use-package marginalia
   :ensure t
-  ;; Bind `marginalia-cycle' locally in the minibuffer.  To make the binding
-  ;; available in the *Completions* buffer, add it to the
-  ;; `completion-list-mode-map'.
   :bind (:map minibuffer-local-map
          ("M-A" . marginalia-cycle))
-
-  ;; The :init section is always executed.
   :init
-
-  ;; Marginalia must be actived in the :init section of use-package such that
-  ;; the mode gets enabled right away. Note that this forces loading the
-  ;; package.
   (marginalia-mode))
 
-(setq completion-styles '(basic substring initials orderless))
-(setq completion-category-overrides
-      '(
-        (file (styles . (basic partial-completion orderless)))
-        (project-file (styles . (flex basic substring partial-completion orderless)))
-        ))
-
-(setq completion-ignore-case t)
-
 (use-package consult
   :ensure t
-  ;; Replace bindings. Lazily loaded due by `use-package'.
   :bind (;; C-c bindings in `mode-specific-map'
          ("C-c M-x" . consult-mode-command)
          ("C-c h" . consult-history)
@@ -126,7 +103,7 @@
 
   :bind
   (("C-." . embark-act)         ;; pick some comfortable binding
-   ("C-;" . embark-dwim)        ;; good alternative: M-.
+   ("M-." . embark-dwim)        ;; good alternative: M-.
    ("C-h B" . embark-bindings)) ;; alternative for `describe-bindings'
 
   :init
@@ -139,9 +116,8 @@
                  nil
                  (window-parameters (mode-line-format . none)))))
 
-;; Consult users will also want the embark-consult package.
 (use-package embark-consult
-  :ensure t ; only need to install it, embark loads it after consult if found
+  :ensure t
   :hook
   (embark-collect-mode . consult-preview-at-point-mode))