diff --git a/modules/completion/corfu/README.org b/modules/completion/corfu/README.org index 94eb2ae16..abe51915e 100644 --- a/modules/completion/corfu/README.org +++ b/modules/completion/corfu/README.org @@ -6,11 +6,15 @@ * Description :unfold: This module provides code completion, powered by [[doom-package:corfu]]. -It is recommended to enable either this or [[doom-module::completion company]], in +It is recommended to enable either this or [[doom-module::completion company]] in case you desire pre-configured auto-completion. Corfu is much lighter weight and focused, plus it's built on native Emacs functionality, whereas Company is heavy and highly non-native, but has some extra features and more maturity. +If you choose Corfu, we also highly recomend reading [[https://github.com/minad/corfu][its README]] and [[https://github.com/minad/cape][cape's +README]], as the backend is very configurable and provides many power-user +utilities for fine-tuning. Only some of common behaviors are documented here. + ** Maintainers - [[doom-user:][@LuigiPiucco]] @@ -65,21 +69,20 @@ characters, by means of [[kbd:][C-SPC]] at any moment or [[kbd:][TAB]] on a line indentation. Many styles of completion are documented below, which can be composed to suit the user. The following keybindings are generally available: -| Keybind | Description | -|---------+---------------------------------------------| -| [[kbd:][C-n]] | Go to next candidate | -| [[kbd:][C-p]] | Go to previous candidate | -| [[kbd:][C-u]] | (evil) Go to next candidate page | -| [[kbd:][C-d]] | (evil) Go to previous candidate page | -| [[kbd:][C-S-n]] | Go to next doc line | -| [[kbd:][C-S-p]] | Go to previous doc line | -| [[kbd:][C-S-h]] | (emacs) Toggle documentation (if available) | -| [[kbd:][C-h]] | (evil) Toggle documentation (if available) | -| [[kbd:][C-S-s]] | Export to minibuffer | -| [[kbd:][DEL]] | Reset completion DWIM | -| [[kbd:][TAB]] | (when not completing) Indent or complete | -| [[kbd:][C-SPC]] | (when not completing) Complete | -| [[kbd:][C-M-i]] | (emacs) (when not completing) Complete | +| Keybind | Description | +|---------+--------------------------------------------| +| [[kbd:][C-n]] | Go to next candidate | +| [[kbd:][C-p]] | Go to previous candidate | +| [[kbd:][C-S-n]] | Go to next doc line | +| [[kbd:][C-S-p]] | Go to previous doc line | +| [[kbd:][C-S-s]] | Export to minibuffer | +| [[kbd:][DEL]] | Reset completion DWIM | +| [[kbd:][TAB]] | (when not completing) Indent or complete | +| [[kbd:][C-SPC]] | (when not completing) Complete | +| [[kbd:][C-u]] | (evil) Go to next candidate page | +| [[kbd:][C-d]] | (evil) Go to previous candidate page | +| [[kbd:][C-h]] | (evil) Toggle documentation (if available) | +| [[kbd:][M-t]] | (emacs) (when not completing) Complete | Bindings in the following sections are additive, and get enabled by including the corresponding ~config.el~ snippets or via flags. Additionally, for users of @@ -133,7 +136,7 @@ first candidate from the start prevents the pass-through. ** Cycle directionally If you'd rather think in directions rather than next/previous, arrow keys and vi movements to control the selection and documentation view are bound by default. -A snippet to unbind them is included after the table. +You may unbind them by setting to nil, see ~map!~'s documentation. | Keybind | Description | |----------+---------------------------------| @@ -146,23 +149,6 @@ A snippet to unbind them is included after the table. | [[kbd:][C-S-j]] | (evil) Go to next doc line | | [[kbd:][C-S-k]] | (evil) Go to previous doc line | -#+begin_src emacs-lisp -(map! (:after corfu - :map corfu-map - "" nil - "" nil - ;; Evil - "C-k" nil - "C-j" nil) - (:after corfu-popupinfo - :map corfu-popupinfo-map - "C-" nil - "C-" nil - ;; Evil - "C-S-k" nil - "C-S-j" nil)) -#+end_src - ** Cycle with [[kbd:][TAB]] You may wish to bind the following [[kbd:][TAB]]-based cycling alternatives with the snippet below the table: @@ -201,44 +187,6 @@ you accidentaly press more than needed. | [[kbd:][SPC]] | (when completing) Quit autocompletion | | [[kbd:][SPC]] | (when completing with separators) Self-insert | -** 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). As an example, set the these binds with the following snippet: - -| Keybind | Description | -|---------+------------------| -| [[kbd:][C-x]] [[kbd:][C-l]] | ~cape-line~ | -| [[kbd:][C-x]] [[kbd:][C-k]] | ~cape-keyword~ | -| [[kbd:][C-x]] [[kbd:][C-f]] | ~cape-file~ | -| [[kbd:][C-x]] [[kbd:][s]] | ~cape-dict~ | -| [[kbd:][C-x]] [[kbd:][C-s]] | ~yasnippet-capf~ | -| [[kbd:][C-x]] [[kbd:][C-n]] | ~cape-dabbrev~ | -| [[kbd:][C-x]] [[kbd:][C-p]] | ~cape-history~ | - -#+begin_src emacs-lisp -;; `corfu-mode-map' is not tied to the popup being visible, whereas `corfu-map' -;; is only active while completing. -(map! :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-n" #'cape-dabbrev - "C-p" #'cape-history) -#+end_src - -** Exporting to the minibuffer -The entries shown in the completion popup can be exported to another -~completion-in-region~ minibuffer, giving access to all the manipulations those -suites allow. 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. - ** Exporting to the minibuffer The entries shown in the completion popup can be exported to another ~completion-in-region~ minibuffer, giving access to all the manipulations those @@ -287,7 +235,7 @@ To add other CAPFs on a mode-per-mode basis, put either of the following in your (add-hook 'some-mode-hook (lambda () (add-hook 'completion-at-point-functions #'some-capf depth t))) #+end_src -~DEPTH~ above is an integer between -100, 100, and defaults to 0 of omitted. Also +~DEPTH~ above is an integer between -100, 100, and defaults to 0 if nil. Also see ~add-hook!~'s documentation for additional ways to call it. ~add-hook~ only accepts the quoted arguments form above. @@ -316,19 +264,20 @@ fixes the issue Cape's implementation has with tree-sitter. #+end_src ** Adding CAPFs to a key -To add other CAPFs to keys, adapt the snippet below into your ~config.el~: +You may want to add other CAPFs to keys, so as to not pollute auto completion +and use only when demanded. To do so, 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 - (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 +(map! :map some-mode-map + "C-x e" #'cape-emoji) #+end_src +It's okay to add to the mode directly because ~completion-at-point~ works +regardless of Corfu (the latter is an enhanced UI for the former). Just note not +all CAPFs are interactive to be called this way, in which case you can use +[[doom-package:cape]]'s adapter to enable this. + * Troubleshooting [[doom-report:][Report an issue?]] diff --git a/modules/completion/corfu/config.el b/modules/completion/corfu/config.el index 192693e28..1bffdf9b5 100644 --- a/modules/completion/corfu/config.el +++ b/modules/completion/corfu/config.el @@ -142,7 +142,6 @@ use the minibuffer such as `query-replace'.") :config (after! savehist (add-to-list 'savehist-additional-variables 'corfu-history))) - (use-package! corfu-popupinfo :hook ((corfu-mode . corfu-popupinfo-mode)) :config diff --git a/modules/config/default/+emacs-bindings.el b/modules/config/default/+emacs-bindings.el index 2402e7885..7c63e68e2 100644 --- a/modules/config/default/+emacs-bindings.el +++ b/modules/config/default/+emacs-bindings.el @@ -537,13 +537,6 @@ "C-p" #'company-search-repeat-backward "C-s" (cmd! (company-search-abort) (company-filter-candidates)))) - (:when (modulep! :completion corfu) - :after corfu - (:map corfu-mode-map - "C-M-i" #'completion-at-point) - (:map corfu-popupinfo-map - "C-S-h" #'corfu-popupinfo-toggle)) - ;;; ein notebooks (:after ein:notebook-multilang :map ein:notebook-multilang-mode-map