dev: merge branch 'pr7002' into emenel

modules/completion/corfu/README.org

@@ -144,16 +144,48 @@ regarding your state. In normal-like states, enter insert then start corfu; in
 visual-like states, perform [[help:evil-change][evil-change]] (which leaves you in insert state) then
 start corfu; in insert-like states, start corfu immediatelly.
 
-** Exporting to the minibuffer (requires [[doom-module::completion vertico]])
-When using the [[doom-module::completion vertico]] module, which pulls in the
-[[doom-package:consult]] package, the entries shown in the completion popup can be
-exported to a consult minibuffer, giving access to all the manipulations the
-Vertico suite allows. For instance, one could use this to export with
-[[doom-package:embark]] via [[kbd:][C-c C-l]] and get a buffer with all candidates.
+** Exporting to the minibuffer
+The entries shown in the completion popup can be exported to a ~completing-read~
+minibuffer, giving access to all the manipulations that suite allows. Using
+Vertico for instance, one could use this to export with [[doom-package:embark]] via
+[[kbd:][C-c C-l]] and get a buffer with all candidates.
+
+** Manually call generic CAPFs
+Completion at point functions have the property that, when called interactively
+via their symbol, they work as a call to ~completion-at-point~ where
+[[var:completion-at-point-functions]] is bound to that CAPF alone. This allows to
+assign generic functions to a binding and call as needed, leaving the default
+value used for most completion tasks much leaner (thus, faster and easier to
+look through). This module provides some such bindings for Evil users (see the
+table below), and you're free map your own of course. Emacs users have to map it
+themselves for now, due to the author's lack of knowledge on ergonomic
+equivalents to the Evil ones. If you have suggestions, though, we'd be happy to
+know!
+
+| Keybind | Description                     |
+|---------+---------------------------------|
+| [[kbd:][C-x]] [[kbd:][C-l]] | (insert-state) ~cape-line~      |
+| [[kbd:][C-x]] [[kbd:][C-k]] | (insert-state) ~cape-keyword~   |
+| [[kbd:][C-x]] [[kbd:][C-f]] | (insert-state) ~cape-file~      |
+| [[kbd:][C-x]] [[kbd:][s]]   | (insert-state) ~cape-dict~      |
+| [[kbd:][C-x]] [[kbd:][C-s]] | (insert-state) ~yasnippet-capf~ |
+| [[kbd:][C-x]] [[kbd:][C-n]] | (insert-state) ~cape-dabbrev~   |
+| [[kbd:][C-x]] [[kbd:][C-p]] | (insert-state) ~cape-history~   |
 
 * Configuration
 A few variables may be set to change behavior of this module:
 
+- [[var:completion-at-point-functions]] ::
+  This is not a module/package variable, but a builtin Emacs one. Even so, it's
+  very important to how Corfu works, so we document it here. It contains a list
+  of functions that are called in turn to generate completion candidates. The
+  regular (non-lexical) value should contain few entries and they should
+  generally be context aware, so as to predict what you need. Additional
+  functions can be added as you get into more and more specific contexts. Also,
+  there may be cases where you know beforehand the kind of candidate needed, and
+  want to enable only that one. For this, the variable may be lexically bound to
+  the correct value, or you may call the CAPF interactively if a single function
+  is all you need.
 - [[var:corfu-auto-delay]] ::
   Number of seconds till completion occurs automatically. Defaults to 0.1.
 - [[var:corfu-auto-prefix]] ::
@@ -180,6 +212,20 @@ To add other CAPFs on a mode-per-mode basis, put either of the following in your
 see ~add-hook!~'s documentation for additional ways to call it. ~add-hook~ only
 accepts the quoted arguments form above.
 
+** Adding CAPFs to a key
+To add other CAPFs to keys, adapt the snippet below into your ~config.el~:
+#+begin_src emacs-lisp
+;; For binding inside `corfu-mode-map'. Line 1 ensures the binding only exists
+;; after some-mode-hook runs. Line 2 is needed only if the binding can't leak
+;; into other Corfu buffers. When neither of the above make sense, the `map!'
+;; call is enough.
+(add-hook! some-mode ; Only needed if the binding is mode-specific
+           (make-local-variable 'corfu-mode-map)
+           (map! :map corfu-mode-map
+                 :prefix "C-x" ; C-x is usually used as prefix, but it's not required
+                 "e" #'cape-emoji)) ; Evil users probably want :i to avoid this in other states
+#+end_src
+
 * Troubleshooting
 [[doom-report:][Report an issue?]]
 

modules/config/default/+evil-bindings.el

@@ -163,6 +163,14 @@
        (:after corfu
         (:map corfu-mode-map
          :e "C-M-i" #'completion-at-point
+         (:prefix "C-x"
+          :i "C-l" #'cape-line
+          :i "C-k" #'cape-keyword
+          :i "C-f" #'cape-file
+          :i "s"   #'cape-dict
+          :i "C-s" #'yasnippet-capf
+          :i "C-n" #'cape-dabbrev
+          :i "C-p" #'cape-history)
          (:unless (modulep! :completion corfu +tng)
           :i "C-SPC" #'completion-at-point
           :n "C-SPC" (cmd! (call-interactively #'evil-insert-state)
@@ -170,9 +178,9 @@
           :v "C-SPC" (cmd! (call-interactively #'evil-change)
                            (call-interactively #'completion-at-point))))
         (:map corfu-map
-          "C-u" (cmd! (let ((corfu-cycle nil))
+          "C-u" (cmd! (let (corfu-cycle)
                         (funcall-interactively #'corfu-next (- corfu-count))))
-          "C-d" (cmd! (let ((corfu-cycle nil))
+          "C-d" (cmd! (let (corfu-cycle)
                         (funcall-interactively #'corfu-next corfu-count)))))
        (:after corfu-popupinfo
         :map corfu-popupinfo-map

modules/config/default/config.el

@@ -460,16 +460,6 @@ Continues comments if executed from a commented line. Consults
 
   (map! :when (modulep! :completion corfu)
         :after corfu
-        (:map corfu-mode-map
-         :prefix "C-x"
-         "C-l" #'cape-line
-         "C-k" #'cape-keyword
-         "C-f" #'cape-file
-         "s"   #'cape-dict
-         "C-s" #'yasnippet-capf
-         "C-o" #'completion-at-point
-         "C-n" #'cape-dabbrev
-         "C-p" #'cape-history)
         (:map corfu-map
          [return] #'corfu-insert
          "RET" #'corfu-insert