diff --git a/modules/completion/corfu/README.org b/modules/completion/corfu/README.org index 4842da058..d88e89969 100644 --- a/modules/completion/corfu/README.org +++ b/modules/completion/corfu/README.org @@ -8,7 +8,7 @@ This module provides code completion, powered by [[doom-package:corfu]]. 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 +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. ** Maintainers @@ -19,21 +19,16 @@ and highly non-native, but has some extra features and more maturity. ** Module flags - +icons :: Display icons beside completion suggestions. -- +tng :: - Known as Tab'n'Go to Company users, changes behavior to invoke completion on - [[kbd:][TAB]]. When Corfu is active, [[kbd:][TAB]] and [[kbd:][S-TAB]] will navigate the completion - candidates. Arrow keys and evil-style movement are still supported. - +orderless :: Pull in [[doom-package:orderless]] if necessary and apply multi-component completion (still needed if [[doom-module::completion vertico]] is active). - +dabbrev :: Enable and configure [[doom-package:dabbrev]] as a close-to-universal CAPF fallback. -- +dict :: - Enable and configure dictionary completion for text modes and related regions - in programming modes. -- +emoji :: - Enable and configure emoji completion via the emoji input method. +- +individual :: + Add bindings for specific CAPFs under the [[kbd:][C-x]] prefix. +- +on-type +on-ret +on-ret-pt +direction +tab :: + Enable corresponding completion-style features. See [[*Usage]]. ** Packages - [[doom-package:corfu]] @@ -68,65 +63,87 @@ words. Snippets may also appear in the candidate list if available. ** Code completion By default, completion gets triggered after typing 2 non-space consecutive -characters, or by means of the [[kbd:][C-SPC]] keybinding at any moment. While the popup -is visible, the following relevant keys are available: +characters, by means of [[kbd:][C-SPC]] at any moment or [[kbd:][TAB]] on a line with proper +indentation. Many styles of completion are offered, which can be composed with +module flags to suit the user; they are described in subsections. The following +keybindings are generally available: -| Keybind | Description | -|----------+-----------------------------------------------------------| -| [[kbd:][]] | Go to next candidate | -| [[kbd:][]] | Go to previous candidate | -| [[kbd:][C-n]] | Go to next candidate | -| [[kbd:][C-p]] | Go to previous candidate | -| [[kbd:][C-j]] | (evil) Go to next candidate | -| [[kbd:][C-k]] | (evil) Go to previous candidate | -| [[kbd:][C-]] | Go to next doc line | -| [[kbd:][C-]] | Go to previous doc line | -| [[kbd:][C-S-n]] | Go to next doc line | -| [[kbd:][C-S-p]] | Go to previous doc line | -| [[kbd:][C-S-j]] | (evil) Go to next doc line | -| [[kbd:][C-S-k]] | (evil) Go to previous doc line | -| [[kbd:][C-h]] | Toggle documentation (if available) | -| [[kbd:][C-S-s]] | Export to minibuffer (if [[doom-module::completion vertico]]) | -| [[kbd:][RET]] | Insert candidate | -| [[kbd:][SPC]] | Quit autocompletion or pass-through after a wildcard | -| [[kbd:][C-SPC]] | Complete (unless [[doom-module::completion corfu +tng]]) | -| [[kbd:][C-SPC]] | (when completing) Insert separator DWIM (see below) | +| 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 | -If you prefer a [[kbd:][TAB]]-centric completion style, enable the [[doom-module::completion -corfu +tng]] flag so that, instead, you trigger completion with [[kbd:][TAB]], getting the -following additional binds: +Bindings in the following sections are additive, and get enabled by the +corresponding module flags. Additionally, for users of evil [[kdb:][C-SPC]] is smart +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. -| Keybind | Description | -|---------+-----------------------------------------------| -| [[kbd:][TAB]] | Complete | -| [[kbd:][TAB]] | (when completing) Go to next candidate | -| [[kbd:][S-TAB]] | (when completing) Go to previous candidate | -| [[kbd:][DEL]] | (when completing) Reset completion DWIM-style | +** Commit on type (~+on-type~) +When the completion popup is visible and the current candidate is previewed into +the buffer, further input commits that candidate as previewed. Note it does not +perform candidate exit actions, such as expanding snippets. This is intended for +people who prefer to leave [[kbd:][RET]] free. -*** Completion in the minibuffer -In the minibuffer, sometimes autocompletion can interfere with your goal; -Imagine you're composing a search pattern incrementally, and you find what you -want early, with only half the word. You then press [[kbd:RET]]. If completion -kicked in as you typed, you may lose the match, since it will complete the -first candidate. On the other hand, if you were paying attention to the -suggestions and selecting one appropriate, that's desired behavior, and you may -even desire to modify the prompt further (if you were composing a command -instead, you may want to extend it after the candidate). To allow better -control, there are 3 confirm bindings when Corfu appears in the minibuffer: +** Commit on [[kbd:][RET]] (~+on-ret~) +Some people prefer to use [[kbd:][RET]] to commit, so here we bind it to Corfu's insertion +function. Note that Corfu allows "no candidate" to be selected, and in that +case, it will just quit without inserting. To make it less obtrusive by default, +the popup starts in this unselected state. See [[var:corfu-preselect]] to alter this +behavior; it can start with the first candidate selected, for instance. -| Keybind | Description | -|-----------+--------------------------------------------------------------------| -| [[kbd:RET]] | Accept the candidate only | -| [[kbd:C-RET]] | Confirm the current prompt only | -| [[kbd:S-RET]] | Accept the candidate then immediately confirm the completed prompt | +| Keybind | Description | +|---------+--------------------------| +| [[kbd:][RET]] | Insert candidate or quit | -- Use [[kbd:RET]] when you want to continue composing after completing; -- Use [[kbd:C-RET]] when you already have the desired string, and completing would - break it; -- Use [[kbd:S-RET]] when you know the composition will be finished after completion - (thus avoiding the need to type [[kbd:RET]] twice); +** Commit on [[kbd:][RET]] with pass-through (~+on-ret-pt~) +This enables [[kbd:][RET]] to work as a finisher like above. The difference is that +without a current candidate, after quitting it passes-through to whatever action +would have happened normally. So if you're in the minibuffer composing a shell +command and press [[kbd:][RET]], unless a candidate is selected, it quits completion then +commits the minibuffer automatically. Contrast to the above, you would need to +press twice to commit. [[var:corfu-preselect]] is important here, as having the +first candidate from the start prevents the pass-through. -** Searching with multiple keywords +| Keybind | Description | +|---------+-------------------------------------------| +| [[kbd:][RET]] | Insert candidate or quit and pass-through | + +** Cycle directionally (~+direction~) +If you'd rather think in directions rather than next/previous, enable arrow keys +and vi movements to control the selection and documentation view. + +| Keybind | Description | +|----------+---------------------------------| +| [[kbd:][]] | Go to next candidate | +| [[kbd:][]] | Go to previous candidate | +| [[kbd:][C-j]] | (evil) Go to next candidate | +| [[kbd:][C-k]] | (evil) Go to previous candidate | +| [[kbd:][C-]] | Go to next doc line | +| [[kbd:][C-]] | Go to previous doc line | +| [[kbd:][C-S-j]] | (evil) Go to next doc line | +| [[kbd:][C-S-k]] | (evil) Go to previous doc line | + +** Cycle with [[kbd:][TAB]] (~+tab~) +Binds [[kbd:][TAB]]-based cycling alternatives. + +| Keybind | Description | +|---------+--------------------------| +| [[kbd:][TAB]] | Go to next candidate | +| [[kbd:][S-TAB]] | Go to previous candidate | + +** Searching with multiple keywords (~+orderless~) If the [[doom-module::completion corfu +orderless]] flag is enabled, users can perform code completion with multiple search keywords by use of space as the separator. More information can be found [[https://github.com/oantolin/orderless#company][here]]. Pressing [[kdb:][C-SPC]] again while @@ -139,28 +156,19 @@ backslash, including the space in the search term, and pressing it with an already escaped separator before point deletes it. Thus, you can cycle back if you accidentaly press more than needed. -Additionally, for users of evil and regular corfu style, [[kdb:][C-SPC]] is smart -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. +| Keybind | Description | +|---------+------------------------------------------------------| +| [[kbd:][C-SPC]] | (when completing) Insert separator DWIM | +| [[kbd:][SPC]] | Quit autocompletion or insert space after a wildcard | -** 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 +** Manually call generic CAPFs (~+individual~) 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! +look through). This module provides some such bindings for those who enable the +~+individual~ module flag. They are listed below: | Keybind | Description | |---------+---------------------------------| @@ -172,6 +180,12 @@ know! | [[kbd:][C-x]] [[kbd:][C-n]] | (insert-state) ~cape-dabbrev~ | | [[kbd:][C-x]] [[kbd:][C-p]] | (insert-state) ~cape-history~ | +** 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. + * Configuration A few variables may be set to change behavior of this module: @@ -191,15 +205,16 @@ A few variables may be set to change behavior of this module: - [[var:corfu-auto-prefix]] :: Number of characters till auto-completion starts to happen. Defaults to 2. - [[var:corfu-on-exact-match]] :: - Configures behavior for exact matches. Its default is nil, and it's - recommended to leave it at that. Otherwise, single matches on snippet keys - expand immediately. + Configures behavior for exact matches. +- [[var:corfu-preselect]] :: + Configures startup selection, choosing between the first candidate or the + prompt. - [[var:+corfu-buffer-scanning-size-limit]] :: Sets the maximum buffer size to be scanned by ~cape-dabbrev~. Defaults to 1 MB. Set this if you are having performance problems using the CAPF. -- [[var:+corfu-want-C-x-bindings]] :: - Enables autocompletion backends to be bound under the ~C-x~ prefix. This - overrides some built-in Emacs keybindings. +- [[var:+corfu-want-minibuffer-completion]] :: + Enables Corfu in the minibuffer, where it may be obtrusive. May also be set + to ~aggresive~ to enable even in some places without ~completion-at-point~. ** Adding CAPFs to a mode To add other CAPFs on a mode-per-mode basis, put either of the following in your @@ -222,11 +237,11 @@ To add other CAPFs to keys, adapt the snippet below into your ~config.el~: ;; 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 +(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 #+end_src * Troubleshooting diff --git a/modules/completion/corfu/autoload.el b/modules/completion/corfu/autoload.el index fcac8babe..1df01bdaf 100644 --- a/modules/completion/corfu/autoload.el +++ b/modules/completion/corfu/autoload.el @@ -1,13 +1,5 @@ ;;; completion/corfu/autoload.el -*- lexical-binding: t; -*- -;;;###autoload -(defun +corfu-complete-and-exit-minibuffer () - (interactive) - (if (>= corfu--index 0) - (corfu-complete) - (corfu-insert)) - (exit-minibuffer)) - ;;;###autoload (defun +corfu-move-to-minibuffer () "Move the current list of candidates to your choice of minibuffer completion UI." diff --git a/modules/completion/corfu/config.el b/modules/completion/corfu/config.el index 7c860e47c..a576a7dc4 100644 --- a/modules/completion/corfu/config.el +++ b/modules/completion/corfu/config.el @@ -3,9 +3,6 @@ (defvar +corfu-buffer-scanning-size-limit (* 1 1024 1024) ; 1 MB "Size limit for a buffer to be scanned by `cape-dabbrev'.") -(defvar +corfu-want-C-x-bindings t - "Whether `C-x' is a completion prefix in Evil insert state.") - (defvar +corfu-want-minibuffer-completion t "Whether to enable Corfu in the minibuffer. Setting this to `aggressive' will enable Corfu in more commands which @@ -50,22 +47,17 @@ use the minibuffer such as `query-replace'.") t) corfu-cycle t corfu-separator (when (modulep! +orderless) ?\s) - corfu-preselect (if (modulep! +tng) 'prompt 'valid) + corfu-preselect 'prompt corfu-count 16 corfu-max-width 120 - corfu-preview-current 'insert + corfu-preview-current (if (modulep! +on-type) 'insert t) corfu-on-exact-match nil corfu-quit-at-boundary (if (modulep! +orderless) 'separator t) corfu-quit-no-match (if (modulep! +orderless) 'separator t) - ;; In the case of +tng, TAB should be smart regarding completion; - ;; However, it should otherwise behave like normal, whatever normal was. - tab-always-indent (if (modulep! +tng) 'complete tab-always-indent)) + tab-always-indent 'complete) (add-to-list 'completion-category-overrides `(lsp-capf (styles ,@completion-styles))) (add-to-list 'corfu-auto-commands #'lispy-colon) - (add-to-list 'corfu-continue-commands #'+corfu-move-to-minibuffer) - - (add-hook 'evil-insert-state-exit-hook #'corfu-quit) (when (modulep! +icons) @@ -116,28 +108,6 @@ use the minibuffer such as `query-replace'.") "\\(TAGS\\|tags\\|ETAGS\\|etags\\|GTAGS\\|GRTAGS\\|GPATH\\)\\(<[0-9]+>\\)?") dabbrev-upcase-means-case-search t) (add-to-list 'dabbrev-ignored-buffer-modes 'pdf-view-mode))) - ;; Complete emojis :). - (when (and (modulep! +emoji) (> emacs-major-version 28)) - (add-hook! (prog-mode conf-mode) - (defun +corfu-add-cape-emoji-h () - (add-hook 'completion-at-point-functions - (cape-capf-predicate (cape-capf-prefix-length #'cape-emoji 1) - #'+corfu-in-doc-or-comment-p) - 10 t))) - (add-hook! text-mode - (defun +corfu-add-cape-emoji-text-h () - (add-hook 'completion-at-point-functions - (cape-capf-prefix-length #'cape-emoji 1) 10 t)))) - ;; Enable dictionary-based autocompletion. - (when (modulep! +dict) - (add-hook! (prog-mode conf-mode) - (defun +corfu-add-cape-dict-h () - (add-hook 'completion-at-point-functions - (cape-capf-predicate #'+corfu-in-doc-or-comment-p #'cape-dict) - 40 t))) - (add-hook! text-mode - (defun +corfu-add-cape-dict-text-h () - (add-hook 'completion-at-point-functions #'cape-dict 40 t)))) ;; Make these capfs composable. (advice-add #'comint-completion-at-point :around #'cape-wrap-nonexclusive) diff --git a/modules/config/default/+evil-bindings.el b/modules/config/default/+evil-bindings.el index 741083f63..f636a443c 100644 --- a/modules/config/default/+evil-bindings.el +++ b/modules/config/default/+evil-bindings.el @@ -163,15 +163,6 @@ (:after corfu (:map corfu-mode-map :e "C-M-i" #'completion-at-point - (:when +corfu-want-C-x-bindings - (: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) @@ -187,8 +178,9 @@ :map corfu-popupinfo-map ;; Reversed because popupinfo assumes opposite of what feels intuitive ;; with evil. - "C-S-k" #'corfu-popupinfo-scroll-down - "C-S-j" #'corfu-popupinfo-scroll-up + (:when (modulep! :completion corfu +direction) + "C-S-k" #'corfu-popupinfo-scroll-down + "C-S-j" #'corfu-popupinfo-scroll-up) "C-h" #'corfu-popupinfo-toggle))) ;;; :completion (separate) diff --git a/modules/config/default/config.el b/modules/config/default/config.el index fa98a80a8..73bddc77c 100644 --- a/modules/config/default/config.el +++ b/modules/config/default/config.el @@ -460,56 +460,65 @@ Continues comments if executed from a commented line. Consults (map! :when (modulep! :completion corfu) :after corfu + (:map corfu-mode-map + :when (modulep! :completion corfu +individual) + :prefix "C-x" + :gi "C-l" #'cape-line + :gi "C-k" #'cape-keyword + :gi "C-f" #'cape-file + :gi "s" #'cape-dict + :gi "C-s" #'yasnippet-capf + :gi "C-n" #'cape-dabbrev + :gi "C-p" #'cape-history) (:map corfu-map "C-S-s" #'+corfu-move-to-minibuffer "C-p" #'corfu-previous "C-n" #'corfu-next (:when (modulep! :completion corfu +orderless) [remap completion-at-point] #'+corfu-smart-sep-toggle-escape) - (:when (modulep! :completion corfu +tng) + (:when (modulep! :completion corfu +tab) :gi [tab] #'corfu-next :gi "TAB" #'corfu-next :gi [backtab] #'corfu-previous :gi "S-TAB" #'corfu-previous)) (:after corfu-popupinfo :map corfu-popupinfo-map - "C-" #'corfu-popupinfo-scroll-down - "C-" #'corfu-popupinfo-scroll-up + (:when (modulep! :completion corfu +direction) + "C-" #'corfu-popupinfo-scroll-down + "C-" #'corfu-popupinfo-scroll-up) "C-S-p" #'corfu-popupinfo-scroll-down "C-S-n" #'corfu-popupinfo-scroll-up "C-S-u" (cmd! (funcall-interactively #'corfu-popupinfo-scroll-down corfu-popupinfo-min-height)) - "C-S-d" (cmd! (funcall-interactively #'corfu-popupinfo-scroll-up corfu-popupinfo-min-height))) - (:when (not (modulep! :completion corfu +tng)) - (:map corfu-map - "C-" `(menu-item "Conclude the minibuffer" exit-minibuffer - :filter ,(lambda (cmd) (when (minibufferp nil t) cmd))) - "S-" `(menu-item "Insert completion and conclude" - +corfu-complete-and-exit-minibuffer - :filter ,(lambda (cmd) (when (minibufferp nil t) cmd)))))) - (when-let ((cmds-del (and (modulep! :completion corfu +tng) - `(menu-item "Reset completion" corfu-reset - :filter ,(lambda (cmd) - (when (and (>= corfu--index 0) - (eq corfu-preview-current 'insert)) - cmd))))) - (cmds-ret `(menu-item "Insert completion" corfu-insert - :filter ,(lambda (cmd) - (cond ((eq corfu--index -1) - (corfu-quit)) - ((and (modulep! :completion corfu +tng) - (eq corfu-preview-current 'insert) - (minibufferp nil t)) - (corfu-insert) - nil) - (t - cmd)))))) + "C-S-d" (cmd! (funcall-interactively #'corfu-popupinfo-scroll-up corfu-popupinfo-min-height)))) + (when-let ((cmds-del + `(menu-item "Reset completion" corfu-reset + :filter ,(lambda (cmd) + (interactive) + (when (and (>= corfu--index 0) + (eq corfu-preview-current 'insert)) + cmd)))) + (cmds-ret-pt + `(menu-item "Insert completion or pass-through" corfu-insert + :filter ,(lambda (cmd) + (interactive) + (if (>= corfu--index 0) + cmd + (corfu-quit)))))) (map! :when (modulep! :completion corfu) :after corfu :map corfu-map [backspace] cmds-del "DEL" cmds-del - :ig [return] cmds-ret - :ig "RET" cmds-ret)) + (:when (modulep! :completion corfu +on-ret) + :gi [return] #'corfu-insert + :gi "RET" #'corfu-insert) + (:when (modulep! :completion corfu +on-ret-pt) + :gi [return] cmds-ret-pt + :gi "RET" cmds-ret-pt) + (:unless (or (modulep! :completion corfu +on-ret) + (modulep! :completion corfu +on-ret-pt)) + [return] nil + "RET" nil))) ;; Smarter C-a/C-e for both Emacs and Evil. C-a will jump to indentation. ;; Pressing it again will send you to the true bol. Same goes for C-e, except