doomemacs/modules/completion/corfu

:completion corfu

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
• Usage
  • Code completion
  • Commit on type (+on-type)
  • Commit on RET (+on-ret)
  • Commit on RET with pass-through (+on-ret-pt)
  • Cycle directionally (+direction)
  • Cycle with TAB (+tab)
  • Searching with multiple keywords (+orderless)
  • Manually call generic CAPFs (+individual)
  • Exporting to the minibuffer
• Configuration
  • Adding CAPFs to a mode
  • Adding CAPFs to a key
• Troubleshooting
• Frequently asked questions
• Appendix

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

• @LuigiPiucco

Become a maintainer?

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.

+individual

Add bindings for specific CAPFs under the C-x prefix.

+on-type +on-ret +on-ret-pt +direction +tab

Enable corresponding completion-style features. See /emenel/doomemacs/src/commit/03f065df9f95a79633019dadf7b44ab1fe701289/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 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
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 the corresponding module 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 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 RET free.

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 (+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
<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

Cycle with TAB (+tab)

Binds TAB-based cycling alternatives.

Keybind	Description
TAB	Go to next candidate
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 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	(when completing) Insert separator DWIM
SPC	Quit autocompletion or insert space after a wildcard

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 those who enable the +individual module flag. They are listed below:

Keybind	Description
C-x C-l	(insert-state) cape-line
C-x C-k	(insert-state) cape-keyword
C-x C-f	(insert-state) cape-file
C-x s	(insert-state) cape-dict
C-x C-s	(insert-state) yasnippet-capf
C-x C-n	(insert-state) cape-dabbrev
C-x 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 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-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 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 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.

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 states

Troubleshooting

Report an issue?

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?