doomemacs/modules/completion/corfu

:completion corfu

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
• Usage
  • Code completion
    • Completion in the minibuffer
  • Searching with multiple keywords
  • Exporting to the minibuffer
  • Manually call generic CAPFs
• 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.

+tng

Known as Tab'n'Go to Company users, changes behavior to invoke completion on TAB. When Corfu is active, TAB and 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.

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, or by means of the C-SPC keybinding at any moment. While the popup is visible, the following relevant keys are available:

Keybind	Description
<down>	Go to next candidate
<up>	Go to previous candidate
C-n	Go to next candidate
C-p	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-n	Go to next doc line
C-S-p	Go to previous doc line
C-S-j	(evil) Go to next doc line
C-S-k	(evil) Go to previous doc line
C-h	Toggle documentation (if available)
C-S-s	Export to minibuffer (if doom-module::completion vertico)
RET	Insert candidate
SPC	Quit autocompletion or pass-through after a wildcard
C-SPC	Complete (unless doom-module::completion corfu +tng)
C-SPC	(when completing) Insert separator DWIM (see below)

If you prefer a TAB-centric completion style, enable the [[doom-module::completion corfu +tng]] flag so that, instead, you trigger completion with TAB, getting the following additional binds:

Keybind	Description
TAB	Complete
TAB	(when completing) Go to next candidate
S-TAB	(when completing) Go to previous candidate
DEL	(when completing) Reset completion DWIM-style

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:

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

• 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);

Searching with multiple keywords

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.

Additionally, for users of evil and regular corfu style, 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.

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

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. Its default is nil, and it's recommended to leave it at that. Otherwise, single matches on snippet keys expand immediately.

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.

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 ; 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

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?