| .. | ||
| autoload.el | ||
| config.el | ||
| packages.el | ||
| README.org | ||
:completion corfu
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 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.
Maintainers
Module flags
- +icons
- Display icons beside completion suggestions.
- +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.
- +on-ret +on-ret-pt
- Enable corresponding completion-style features. See /emenel/doomemacs/src/commit/afe9fa896f0b5455f860f0da4c6e1abcfef0f27f/modules/completion/corfu/*Usage.
Packages
- doom-package:corfu
- doom-package:cape
- doom-package:nerd-icons-corfu if doom-module::completion corfu +icons
- doom-package:orderless if doom-module::completion corfu +orderless
- doom-package:corfu-terminal if doom-module::os tty
- doom-package:yasnippet-capf if doom-module::editor snippets
Hacks
No hacks documented for this module.
TODO Changelog
This module does not have a changelog yet.
Installation
Enable this module in your doom! block.
This module has no direct requirements, but some languages may have their own
requirements to fulfill before you get code completion in them (and some
languages may lack code completion support altogether). Run $ doom doctor to
find out if you're missing any dependencies. Note that Corfu may have support
for completions in languages that have no development intelligence, since it
supports generic, context insensitive candidates such as file names or recurring
words. Snippets may also appear in the candidate list if available.
TODO Usage
🔨 This module's usage documentation is incomplete. Complete it?
Code completion
By default, completion gets triggered after typing 2 non-space consecutive characters, by means of C-SPC at any moment or TAB on a line with proper indentation. Many styles of completion are documented below, which can be composed to suit the user. The following keybindings are generally available:
| Keybind | Description |
|---|---|
| C-n | Go to next candidate |
| C-p | Go to previous candidate |
| C-u | (evil) Go to next candidate page |
| C-d | (evil) Go to previous candidate page |
| C-S-n | Go to next doc line |
| C-S-p | Go to previous doc line |
| C-S-h | (emacs) Toggle documentation (if available) |
| C-h | (evil) Toggle documentation (if available) |
| C-S-s | Export to minibuffer |
| DEL | Reset completion DWIM |
| TAB | (when not completing) Indent or complete |
| C-SPC | (when not completing) Complete |
| C-M-i | (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
evil, C-SPC is smart regarding your state. In normal-like states, enter insert
then start corfu; in visual-like states, perform evil-change (which leaves you
in insert state) then start corfu; in insert-like states, start corfu
immediatelly.
Commit preview on type
When the completion popup is visible, by default the current candidate is
previewed into the buffer, and further input commits that candidate as previewed
(note it does not perform candidate exit actions, such as expanding snippets).
If neither +on-ret or +on-ret-pt are enabled, this becomes the only default
way to commit a candidate (RET is unbound in that case).
The feature is in line with other common editors, but if you prefer the preview to be only visual or for there to be no preview, configure var:corfu-preview-current.
;; Non-inserting preview
(setq corfu-preview-current t)
;; No preview
(setq corfu-preview-current nil)
Commit on RET (+on-ret)
Some people prefer to use 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 |
|---|---|
| RET | Insert candidate or quit |
Commit on RET with pass-through (+on-ret-pt)
This enables 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 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.
| Keybind | Description |
|---|---|
| RET | Insert candidate or quit and 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.
| Keybind | Description |
|---|---|
| <down> | Go to next candidate |
| <up> | Go to previous candidate |
| C-j | (evil) Go to next candidate |
| C-k | (evil) Go to previous candidate |
| C-<down> | Go to next doc line |
| C-<up> | Go to previous doc line |
| C-S-j | (evil) Go to next doc line |
| C-S-k | (evil) Go to previous doc line |
(map! (:after corfu
:map corfu-map
"<up>" nil
"<down>" nil
;; Evil
"C-k" nil
"C-j" nil)
(:after corfu-popupinfo
:map corfu-popupinfo-map
"C-<up>" nil
"C-<down>" nil
;; Evil
"C-S-k" nil
"C-S-j" nil))Cycle with TAB
You may wish to bind the following TAB-based cycling alternatives with the snippet below the table:
| Keybind | Description |
|---|---|
| TAB | Go to next candidate |
| S-TAB | Go to previous candidate |
(map! :after corfu
:map corfu-map
[tab] #'corfu-next
"TAB" #'corfu-next
[backtab] #'corfu-previous
"S-TAB" #'corfu-previous)
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 here. Pressing C-SPC again while completing inserts a space as separator. This allows searching with space-separated terms; each piece will match individually and in any order, with smart casing. Pressing just SPC acts as normal and quits completion, so that when typing sentences it doesn't try to complete the whole sentence instead of just the word. Pressing C-SPC with point after a separator escapes it with a 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.
| Keybind | Description |
|---|---|
| C-SPC | (evil) (when completing) Insert separator DWIM |
| M-SPC | (emacs) (when completing) Insert separator DWIM |
| SPC | (when completing) Quit autocompletion |
| 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 |
|---|---|
| C-x C-l | cape-line |
| C-x C-k | cape-keyword |
| C-x C-f | cape-file |
| C-x s | cape-dict |
| C-x C-s | yasnippet-capf |
| C-x C-n | cape-dabbrev |
| C-x C-p | cape-history |
;; `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)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 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
suites allow. Using Vertico for instance, one could use this to export with
doom-package:embark via C-c C-l and get a buffer with all candidates.
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
- Number of characters till auto-completion starts to happen. Defaults to 2.
- var:corfu-on-exact-match
- Configures behavior for exact matches.
- var:corfu-preselect
- Configures startup selection, choosing between the first candidate or the prompt.
- var:corfu-preview-current
- Configures current candidate preview.
- 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-minibuffer-completion
-
Enables Corfu in the minibuffer, where it may be obtrusive. May also be set
to
aggresiveto enable even in some places withoutcompletion-at-point.
Adding CAPFs to a mode
To add other CAPFs on a mode-per-mode basis, put either of the following in your
config.el:
(add-hook! some-mode (add-hook 'completion-at-point-functions #'some-capf depth t))
;; OR, but note the different call signature
(add-hook 'some-mode-hook (lambda () (add-hook 'completion-at-point-functions #'some-capf depth t)))
DEPTH above is an integer between -100, 100, and defaults to 0 of omitted. Also
see add-hook!'s documentation for additional ways to call it. add-hook only
accepts the quoted arguments form above.
For programming modes where you want a CAPF to be active only in documentation and comments, define the following function and use it as a Cape predicate. It fixes the issue Cape's implementation has with tree-sitter.
;;;###autoload
(defun +corfu-in-doc-or-comment-p (&optional _sym)
"Return non-nil if point is in a docstring or comment."
(or (nth 4 (syntax-ppss))
(when-let ((faces '(font-lock-comment-face
font-lock-doc-face
tree-sitter-hl-face:doc
tree-sitter-hl-face:comment))
(fs (get-text-property (point) 'face)))
(if (listp fs)
(cl-loop for f in fs
if (memq f faces)
return t)
(memq fs faces)))))
;; Use this as #'some-capf above
(cape-capf-predicate #'another-capf #'+corfu-in-doc-or-comment-p)Adding CAPFs to a key
To add other CAPFs to keys, adapt the snippet below into your config.el:
;; 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 statesTroubleshooting
If you have performance issues with cape-dabbrev, the first thing I recommend
doing is to look at the list of buffers Dabbrev is scanning:
(dabbrev--select-buffers) ; => (#<buffer README.org> #<buffer config.el<3>> #<buffer cape.el> ...)
(length (dabbrev--select-buffers)) ; => 37
… and modify dabbrev-ignored-buffer-regexps or dabbrev-ignored-buffer-modes
accordingly.
Frequently asked questions
This module has no FAQs yet. Ask one?
TODO Appendix
🔨 This module has no appendix yet. Write one?