Home
See this video for a nice overview of Corfu and a bit about Cape, as well as a comparison with other tools.
Lsp-mode is an Emacs package which provides an LSP client for Emacs. It provides completions for a wide array of languages and types. It does this by consulting external LSP server processes. LSP servers look at the text in the region and send a list of suggested completions.
The main thing you need to tune is the completion style. LSP servers do not know
about or respect the “completion style” in Emacs (they have their own “styles”).
For example, with text foo they may provide completions foobar, frodo, tofoo,
atafondillo, etc. So here the local Emacs style you configure matters. If you
have setup a “prefix-only” Emacs style like basic, all those completions the LSP
server provided will be filtered; only foobar in the list above will be shown.
If you want to use a builtin completion style it is recommended to either use
substring or flex. The substring style is slightly limited in that it matches
substrings only, so you will get the candidates foobar and tofoo. The flex style
matches all of the candidates.
(use-package lsp-mode
:custom
(lsp-completion-provider :none) ;; we use Corfu!
:init
(defun my/lsp-mode-setup-completion ()
(setf (alist-get 'styles (alist-get 'lsp-capf completion-category-defaults))
'(flex))) ;; Configure flex
:hook
(lsp-completion-mode . my/lsp-mode-setup-completion))An example of a much more flexible and powerful Emacs completion style is Orderless, which can find text anywhere in the string. You can even use spaces in the buffer to add additional regex or normal searches. And the beauty is with Corfu and Orderless, this filtering and selection happens instantly in Emacs, without having to re-contact the LSP server! This can be much faster for slow servers.
(use-package orderless
:init
;; Tune the global completion style settings to your liking!
;; This affects the minibuffer and non-lsp completion at point.
(setq completion-styles '(orderless partial-completion basic)
completion-category-defaults nil
completion-category-overrides nil))
(use-package lsp-mode
:custom
(lsp-completion-provider :none) ;; we use Corfu!
:init
(defun my/lsp-mode-setup-completion ()
(setf (alist-get 'styles (alist-get 'lsp-capf completion-category-defaults))
'(orderless))) ;; Configure orderless
:hook
(lsp-completion-mode . my/lsp-mode-setup-completion))To make sure every single completion candidate comes through, we use Orderless’
“dispatcher” capability to setup the orderless-flex style for its 1st search
term (the string you are completing). You can skip this if you prefer to filter
a bit what the LSP servers has provided when Corfu first pops up (I mean, did I
really type foo if I wanted atafondillo?).
;; Optional cape package.
;; See the Cape README for more tweaks!
(use-package cape)
(use-package orderless
:init
;; Tune the global completion style settings to your liking!
;; This affects the minibuffer and non-lsp completion at point.
(setq completion-styles '(orderless partial-completion basic)
completion-category-defaults nil
completion-category-overrides nil))
(use-package lsp-mode
:custom
(lsp-completion-provider :none) ;; we use Corfu!
:init
(defun my/orderless-dispatch-flex-first (_pattern index _total)
(and (eq index 0) 'orderless-flex))
(defun my/lsp-mode-setup-completion ()
(setf (alist-get 'styles (alist-get 'lsp-capf completion-category-defaults))
'(orderless))
;; Optionally configure the first word as flex filtered.
(add-hook 'orderless-style-dispatchers #'my/orderless-dispatch-flex-first nil 'local)
;; Optionally configure the cape-capf-buster.
(setq-local completion-at-point-functions (list (cape-capf-buster #'lsp-completion-at-point))))
:hook
(lsp-completion-mode . my/lsp-mode-setup-completion))The one additional feature we have used here is Cape’s cape-capf-buster. This
also isn’t entirely necessary, but it gives some nicer behavior when you alter
the original text during completion (e.g. while completing get, you delete back
to ge).
See below for examples of grouping results from other completion sources using Cape.
Eglot is an Emacs packages which provide completions for a wide array of languages and types. It does this by consulting external LSP language server processes. LSP servers look at the text in the region and send a list of suggested completions.
The LSP server assumes that the candidates are retrieved on every change to the
buffer and we can rely on the LSP server to do the heavy lifting and provide a
continuously update list of completions. The problem is that LSP servers are
unaware of Emacs completion-styles, therefore the candidates from the language
server are only post-filtered by the completion style.
Corfu retrieves the candidate completion table once at the beginning of a
completion session and doesn’t reload it while the word is being typed. This is
advantageous for most completion-at-point-functions since it opens up caching
opportunities. Eglot completion function doesn’t refresh the completion table
itself. This is problematic, as language servers often only provide limited list
of completions. Therefore, when using auto completion and typing slowly,
possible completion candidates may be missing, because the initial list was
missing the intended string.
This behavior can be changed with the cache buster from Cape, which ensures that the completion table is refreshed such that the candidates are always obtained again from the server.
(advice-add 'eglot-completion-at-point :around #'cape-wrap-buster)Retrieving the candidates on every key press can be seen as a disadvantage,
since it decreases performance. This matters in particular if your language
server returns many candidates (or even a complete set of candidates) right away
on the first invocation of completion. Depending on your language server you may
or may not want the cape-wrap-buster. See also the next section about requesting
more candidates from the Lsp server by default.
Corfu supports the Orderless completion style. As soon as you press M-SPC, a
space is inserted and Orderless filtering starts. The candidates are not updated
again from the server. Instead the existing candidates are only post-filtered
with Orderless. This feature works always, with or without cape-wrap-buster.
Note that this feature is Orderless-specific. See the next section.
Instead of relying on the LSP server to continuously filter the list of possible completions, we can use a completion style like Orderless to filter that list.
Eglot adjusts the completion styles by default. It sets the style for the eglot
category to flex in completion-category-defaults. The flex style is not used to
do any “flex” or “fuzzy” matching, Eglot uses it mainly to provide highlighting.
In LSP interactions the completion candidate filtering logic is determined by
the LSP server outside of Emacs’s control. If you want to use Eglot in
combination with Orderless or another completion style you should override this
setting.
;; Option 1: Specify explicitly to use Orderless for Eglot
(setq completion-category-overrides '((eglot (styles orderless))
(eglot-capf (styles orderless))))
;; Option 2: Undo the Eglot modification of completion-category-defaults
(with-eval-after-load 'eglot
(setq completion-category-defaults nil))
;; Enable cache busting, depending on if your server returns
;; sufficiently many candidates in the first place.
(advice-add 'eglot-completion-at-point :around #'cape-wrap-buster)Depending on if Eglot returns all or sufficiently many candidates in the first
place you may or may not need the cape-wrap-buster. Servers usually limit the
completion candidates to a small number, to avoid sending large amounts of data
over the JSONRPC protocol. If the server does not guarantee returning all valid
completions matching the prefix, you will miss potentially valid completions. In
case of doubt, use cape-wrap-buster.
As alternative you can increase the number of returned candidates as described in the next section. This may lead to higher GC pressure.
If you use the Orderless completion style and your LSP server doesn’t give all
completions from Data.Vector. or java.util.list. that exist, you may wish to
request more completions from the server to filter them with Orderless.
WARNING: Your LSP server likely limits completions due to performance concerns and raising the limit could cause performance issues. Keep this in mind for at least a few weeks after changing this setting.
You’ll have to consult your LSP server for it’s configuration details, but Elisp
alists mapping to JSON can be added to eglot-workspace-configuration. Here is an
example for haskell-language-server to request 200 completion candidates:
(setq-default eglot-workspace-configuration
'((haskell (maxCompletions . 200))))When we’re in eglot-mode we want more than the eglot-completion-at-point
function provides. In the following example, we use Cape’s cape-capf-super
function to compose our own completion at point using eglot’s
eglot-completion-at-point, tempel’s tempel-expand and Cape’s cape-file.
(defun my/eglot-capf ()
(setq-local completion-at-point-functions
(list (cape-capf-super
#'eglot-completion-at-point
#'tempel-expand
#'cape-file))))
(add-hook 'eglot-managed-mode-hook #'my/eglot-capf)One might want to set a separator using a key, and when pressing that key twice, it inserts the selected candidate. This saves a keypress and is particularly efficient with “SPC”.
This code can do this:
;; SPC as separator
(setq corfu-separator 32)
;; highly recommanded to use corfu-separator with "32" (space)
(define-key corfu-map (kbd "SPC")
(lambda ()
(interactive)
(if current-prefix-arg
;;we suppose that we want leave the word like that, so do a space
(progn
(corfu-quit)
(insert " "))
(if (and (= (char-before) corfu-separator)
(or
;; check if space, return or nothing after
(not (char-after))
(= (char-after) ?\s)
(= (char-after) ?\n)))
(progn
(corfu-insert)
(insert " "))
(corfu-insert-separator)))))Now you can type “spc” to insert a separator, and “spc spc” to insert the current candidate. Moreover, if you do C-u and then separator, it leaves the word as it is, without completion, and inserts a space.
Corfu works with traditional Emacs completion backends called completion at
point functions (Capfs). Cape provides some additional simple backends as
Capfs, which can be used directly. It also allows you to tweak them, and even
composite them. This examples shows how to set up emacs-lisp mode with a
super Capf composed of two different sources: the normal
elisp-completion-at-point completions and dabbrev candidates from cape-dabbrev.
This is great while hacking on emacs-lisp files, when the symbols aren’t yet
known to Emacs, for example. Corfu will pop-up with both symbols known to emacs,
and (as a backup) additional matching symbols it finds in the file. I put a
minimum length of 5 characters to avoid small word pollution.
It also adds cape-file to the list of completion at point functions, to try as a
“back-up”, e.g. in strings and comments. It also shows how to use another cool
cape feature to add a custom predicate. The predicate is a function which gets
the candidate, and return t if it should be kept. This one drops keywords from
the emacs-lisp candidate list, unless the completion text starts with a `:’.
There are lots of ways to composite together and tweak CAPFs, to supplement your
mode’s completions.
(defun my/ignore-elisp-keywords (cand)
(or (not (keywordp cand))
(eq (char-after (car completion-in-region--data)) ?:)))
(defun my/setup-elisp ()
(setq-local completion-at-point-functions
`(,(cape-capf-super
(cape-capf-predicate
#'elisp-completion-at-point
#'my/ignore-elisp-keywords)
#'cape-dabbrev)
cape-file)
cape-dabbrev-min-length 5))
(add-hook 'emacs-lisp-mode-hook #'my/setup-elisp)Here’s an example of cape working to combine emacs-lisp and dabbrev completion candidates, with corfu, kind-icons, and orderless completion style in-buffer:
If Corfu is not triggering completion with corfu-auto it can be the case that
the command was not called with self-insert-command or one of the other commands
registered in the list corfu-auto-commands. You can fix this by adding the
commands you are missing to the list.
(add-to-list 'corfu-auto-commands 'some-special-insert-command)Using together with prescient.el
prescient.el is a sorting and filtering package. An integration package is
available for Corfu: corfu-prescient (available on MELPA). The mode provided by
the package configures the filtering settings that Corfu uses (completion-styles
and family) buffer locally and configures Corfu’s sorting globally.
;; After installing the package
(corfu-prescient-mode 1)In TAB-and-Go style, if a candidate is selected, then further input commits that candidate unless it is the first one. In order that the first candidate is also committed on further input, add this to your configuration:
(dolist (c (list (cons "SPC" " ")
(cons "." ".")
(cons "," ",")
(cons ":" ":")
(cons ")" ")")
(cons "}" "}")
(cons "]" "]")))
(define-key corfu-map (kbd (car c)) `(lambda ()
(interactive)
(corfu-insert)
(insert ,(cdr c)))))This list can be modified to accommodate anyone’s needs. Note that the inclusion of space assumes that the completion style is “basic”. Also note that the inclusion of “.” disables regex search within the candidate list. A simpler version only including space is this:
(define-key corfu-map (kbd "SPC") (lambda ()
(interactive)
(corfu-insert)
(insert " ")))
Sometimes, sorting using corfu-sort-function is wanted on top of display-sort-function. For example, when recency based sorting is wanted in addition to the sorting provided by an LSP backend (e.g. corfu-history on top of lsp-mode completion). This can be done by using the following combined sorting function:
(defun my-corfu-combined-sort (candidates)
"Sort CANDIDATES using both display-sort-function and corfu-sort-function."
(let ((candidates
(let ((display-sort-func (corfu--metadata-get 'display-sort-function)))
(if display-sort-func
(funcall display-sort-func candidates)
candidates))))
(if corfu-sort-function
(funcall corfu-sort-function candidates)
candidates)))
(setq corfu-sort-override-function #'my-corfu-combined-sort)