emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

module: add :completion corfu

Browse source 
This commit's primary goal is allowing use of
[Corfu](https://github.com/minad/corfu) as an alternative to
[Company](https://github.com/company-mode/company-mode). It introduces a
module under `:completion` for this purpose, plus some conditionals on
other relevant modules to toggle functionality like lsp back-ends and
[Cape](https://github.com/minad/cape) capfs for certain modes.

Other optional or miscellaneous features include:

- Corfu is enabled in the minibuffer if `completion-at-point` is bound;
- Support for displaying the completion's documentation on a secondary
  popup;
- Support for terminal display if :os tty;
- Support for icons if +icons;
This commit is contained in:
Luigi Sartor Piucco 2022-09-24 17:33:32 -03:00
parent 85ce866953
commit 6949451b00
No known key found for this signature in database
GPG key ID: 6FF1A01853A47A66
9 changed files with 422 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

229
modules/completion/corfu/README.org Normal file
View file

@ -0,0 +1,229 @@
#+title: :completion corfu
#+subtitle: Complete with cap(f), cape and a flying feather
#+created: September 9, 2022
#+since: 3.0.0 (#7002)
* 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.
If you choose Corfu, we also highly recomend reading [[https://github.com/minad/corfu][its README]] and [[https://github.com/minad/cape][cape's
README]], as the backend is very configurable and provides many power-user
utilities for fine-tuning. Only some of common behaviors are documented here.
** Maintainers
- [[doom-user:][@LuigiPiucco]]
[[doom-contrib-maintainer:][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).
** 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]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/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.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
By default, completion gets triggered after typing 2 non-space consecutive
characters, by means of [[kbd:][C-SPC]] at any moment or [[kbd:][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 |
|---------+--------------------------------------------|
| [[kbd:][C-n]] | Go to next candidate |
| [[kbd:][C-p]] | Go to previous candidate |
| [[kbd:][C-S-n]] | Go to next doc line |
| [[kbd:][C-S-p]] | Go to previous doc line |
| [[kbd:][C-S-s]] | Export to minibuffer |
| [[kbd:][TAB]] | (when not completing) Indent or complete |
| [[kbd:][C-SPC]] | (when not completing) Complete |
| [[kbd:][C-u]] | (evil) Go to next candidate page |
| [[kbd:][C-d]] | (evil) Go to previous candidate page |
| [[kbd:][C-h]] | (evil) Toggle documentation (if available) |
| [[kbd:][M-t]] | (emacs) (when not completing) Complete |
Bindings in the following sections are additive, and unless otherwise noted, are
enabled by default with configurable behavior. 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.
** 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).
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]].
#+begin_src emacs-lisp
;; Non-inserting preview
(setq corfu-preview-current t)
;; No preview
(setq corfu-preview-current nil)
#+end_src
** Commit on [[kbd:][RET]] with pass-through
A lot of people like 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, we have a custom binding to quit completion and pass-through. To make
it less obtrusive by default, the popup starts in this unselected state. See
[[var:corfu-preselect]] to alter the initial behavior; it can start with the first
one selected, for instance. Then, you have to move one candidate backwards to
pass-through The exact action of [[kbd:][RET]] can be changed via
[[var:+corfu-want-ret-to-confirm]].
| Keybind | Description |
|---------+-----------------------|
| [[kbd:][RET]] | Insert candidate DWIM |
** 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.
You may unbind them by setting to nil, see ~map!~'s documentation.
| Keybind | Description |
|----------+---------------------------------|
| [[kbd:][<down>]] | Go to next candidate |
| [[kbd:][<up>]] | Go to previous candidate |
| [[kbd:][C-j]] | (evil) Go to next candidate |
| [[kbd:][C-k]] | (evil) Go to previous candidate |
| [[kbd:][C-<down>]] | Go to next doc line |
| [[kbd:][C-<up>]] | 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]]
[[kbd:][TAB]]-based cycling alternatives are also bound according to the table below:
| 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
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 [[kbd:][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.
| Keybind | Description |
|---------+-------------------------------------------------|
| [[kbd:][C-SPC]] | (evil) (when completing) Insert separator DWIM |
| [[kbd:][M-SPC]] | (emacs) (when completing) Insert separator DWIM |
| [[kbd:][SPC]] | (when completing) Quit autocompletion |
| [[kbd:][SPC]] | (when completing with separators) Self-insert |
** Exporting to the minibuffer (requires [[doom-module::completion vertico]])
When using the [[doom-module::completion vertico]] module, which pulls in the
[[doom-package:consult]] package, the entries shown in the completion popup can be
exported to a consult minibuffer, giving access to all the manipulations the
Vertico suite allows. 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:
- [[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-want-ret-to-confirm]] ::
Enables commiting with [[RET]] when the popup is visible. Default is ~t~, may be set to
~'minibuffer~ if you want to commit both the completion and the minibuffer when
active. When ~nil~, it is always passed-through.
** Adding CAPFs to a mode
To add other CAPFs on a mode-per-mode basis, put either of the following in your
~config.el~:
#+begin_src emacs-lisp
(add-hook! some-mode (add-to-list 'completion-at-point-functions #'some-capf))
;; OR, but note the different call signature
(add-hook 'some-mode-hook (lambda () (add-to-list 'completion-at-point-functions #'some-capf)))
#+end_src
~DEPTH~ above is an integer between -100, 100, and defaults to 0 if nil. 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~:
#+begin_src emacs-lisp
(map! :map some-mode-map
"C-x e" #'cape-emoji)
#+end_src
It's okay to add to the mode directly because ~completion-at-point~ works
regardless of Corfu (the latter is an enhanced UI for the former). Just note not
all CAPFs are interactive to be called this way, in which case you can use
[[doom-package:cape]]'s adapter to enable this.
* Troubleshooting
[[doom-report:][Report an issue?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

10
modules/completion/corfu/autoload.el Normal file
View file

@ -0,0 +1,10 @@
;;; completion/corfu/autoload.el -*- lexical-binding: t; -*-
;;;###autoload
(defun +corfu-move-to-minibuffer ()
;; Taken from corfu's README.
;; TODO: extend this to other completion front-ends.
(interactive)
(let ((completion-extra-properties corfu--extra)
(completion-cycle-threshold completion-cycling))
(apply #'consult-completion-in-region completion-in-region--data)))

92
modules/completion/corfu/config.el Normal file
View file

@ -0,0 +1,92 @@
;;; completion/corfu/config.el -*- lexical-binding: t; -*-
(defvar +corfu-want-ret-to-confirm t
"Configure how the user expects RET to behave.
Possible values are:
- t (default): Insert candidate if one is selected, pass-through otherwise;
- `minibuffer': Insert candidate if one is selected, pass-through otherwise,
and immediatelly exit if in the minibuffer;
- nil: Pass-through without inserting.")
;;
;;; Packages
(use-package! corfu
:hook (doom-first-input . global-corfu-mode)
:init
(add-hook! 'minibuffer-setup-hook
(defun +corfu-enable-in-minibuffer ()
"Enable Corfu in the minibuffer if `completion-at-point' is bound."
(when (where-is-internal #'completion-at-point (list (current-local-map)))
(setq-local corfu-echo-delay nil)
(corfu-mode +1))))
:config
(setq corfu-auto t
corfu-auto-delay 0.1
corfu-auto-prefix 2
global-corfu-modes '((not
erc-mode
circe-mode
help-mode
gud-mode
vterm-mode)
t)
corfu-cycle t
corfu-separator (when (modulep! +orderless) ?\s)
corfu-preselect 'prompt
corfu-count 16
corfu-max-width 120
corfu-preview-current 'insert
corfu-on-exact-match nil
corfu-quit-at-boundary (if (modulep! +orderless) 'separator t)
corfu-quit-no-match (if (modulep! +orderless) 'separator t)
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))
(use-package! cape
:defer t
:init
(add-hook! prog-mode
(defun +corfu-add-cape-file-h ()
(add-to-list 'completion-at-point-functions #'cape-file)))
(add-hook! (org-mode markdown-mode)
(defun +corfu-add-cape-elisp-block-h ()
(add-hook 'completion-at-point-functions #'cape-elisp-block 0 t)))
;; Make these capfs composable.
(advice-add #'lsp-completion-at-point :around #'cape-wrap-noninterruptible)
(advice-add #'lsp-completion-at-point :around #'cape-wrap-nonexclusive)
(advice-add #'comint-completion-at-point :around #'cape-wrap-nonexclusive)
(advice-add #'eglot-completion-at-point :around #'cape-wrap-nonexclusive)
(advice-add #'pcomplete-completions-at-point :around #'cape-wrap-nonexclusive)
;; From the `cape' readme. Without this, Eshell autocompletion is broken on
;; Emacs28.
(when (< emacs-major-version 29)
(advice-add 'pcomplete-completions-at-point :around #'cape-wrap-silent)
(advice-add 'pcomplete-completions-at-point :around #'cape-wrap-purify)))
(use-package! corfu-terminal
:when (not (display-graphic-p))
:hook ((corfu-mode . corfu-terminal-mode)))
;;
;;; Extensions
(use-package! corfu-history
:hook ((corfu-mode . corfu-history-mode))
:config
(after! savehist (add-to-list 'savehist-additional-variables 'corfu-history)))
(use-package! corfu-popupinfo
:hook ((corfu-mode . corfu-popupinfo-mode))
:config
(setq corfu-popupinfo-delay '(0.5 . 1.0)))
(use-package! nerd-icons-corfu
:when (modulep! +icons)
:defer t
:init
(after! corfu
(add-to-list 'corfu-margin-formatters #'nerd-icons-corfu-formatter)))

11
modules/completion/corfu/packages.el Normal file
View file

@ -0,0 +1,11 @@
;; -*- no-byte-compile: t; -*-
;;; completion/corfu/packages.el
(package! corfu :pin "c1e7b6190b00158e67347b4db0a8f7964e5d2f8b")
(package! cape :pin "a397a0c92de38277b7f835fa999fac400a764908")
(when (modulep! +icons)
(package! nerd-icons-corfu :pin "7077bb76fefc15aed967476406a19dc5c2500b3c"))
(when (modulep! +orderless)
(package! orderless :pin "b24748093b00b37c3a572c4909f61c08fa27504f"))
(when (modulep! :os tty)
(package! corfu-terminal :pin "501548c3d51f926c687e8cd838c5865ec45d03cc"))

2
modules/config/default/+emacs-bindings.el
View file

@ -511,7 +511,7 @@
"C-x C-b" #'ibuffer
"C-x K" #'doom/kill-this-buffer-in-all-windows
;;; company-mode
;;; completion (in-buffer)
(:when (modulep! :completion company)
"C-;" #'+company/complete
(:after company

47
modules/config/default/+evil-bindings.el
View file

@ -43,7 +43,10 @@
#'yas-expand
(and (bound-and-true-p company-mode)
(modulep! :completion company +tng))
#'company-indent-or-complete-common)
#'company-indent-or-complete-common
(and (bound-and-true-p corfu-mode)
(modulep! :completion corfu))
#'completion-at-point)
:m [tab] (cmds! (and (modulep! :editor snippets)
(evil-visual-state-p)
(or (eq evil-visual-selection 'line)
@ -127,7 +130,7 @@
;;
;;; Module keybinds
;;; :completion
;;; :completion (in-buffer)
(map! (:when (modulep! :completion company)
:i "C-@" (cmds! (not (minibufferp)) #'company-complete-common)
:i "C-SPC" (cmds! (not (minibufferp)) #'company-complete-common)
@ -156,7 +159,38 @@
"C-s" #'company-filter-candidates
[escape] #'company-search-abort)))
(:when (modulep! :completion ivy)
(:when (modulep! :completion corfu)
(:after corfu
(:map corfu-mode-map
:i "C-SPC" #'completion-at-point
:n "C-SPC" (cmd! (call-interactively #'evil-insert-state)
(call-interactively #'completion-at-point))
:v "C-SPC" (cmd! (call-interactively #'evil-change)
(call-interactively #'completion-at-point)))
(:map corfu-map
:i "C-SPC" #'corfu-insert-separator
"C-k" #'corfu-previous
"C-j" #'corfu-next
"C-u" (cmd! (let (corfu-cycle)
(funcall-interactively #'corfu-next (- corfu-count))))
"C-d" (cmd! (let (corfu-cycle)
(funcall-interactively #'corfu-next corfu-count)))))
(:after corfu-popupinfo
:map corfu-popupinfo-map
"C-h" #'corfu-popupinfo-toggle
;; 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
"C-<up>" #'corfu-popupinfo-scroll-down
"C-<down>" #'corfu-popupinfo-scroll-up
"C-S-p" #'corfu-popupinfo-scroll-down
"C-S-n" #'corfu-popupinfo-scroll-up
"C-S-u" (cmd!! #'corfu-popupinfo-scroll-down nil corfu-popupinfo-min-height)
"C-S-d" (cmd!! #'corfu-popupinfo-scroll-up nil corfu-popupinfo-min-height))))
;;; :completion (separate)
(map! (:when (modulep! :completion ivy)
(:after ivy
:map ivy-minibuffer-map
"C-SPC" #'ivy-call-and-recenter ; preview file
@ -169,7 +203,8 @@
[C-return] #'+ivy/git-grep-other-window-action))
(:when (modulep! :completion helm)
(:after helm :map helm-map
(:after helm
:map helm-map
[remap next-line] #'helm-next-line
[remap previous-line] #'helm-previous-line
[left] #'left-char
@ -387,9 +422,9 @@
:desc "Incoming call hierarchy" "y" #'lsp-treemacs-call-hierarchy
:desc "Outgoing call hierarchy" "Y" (cmd!! #'lsp-treemacs-call-hierarchy t)
:desc "References tree" "R" (cmd!! #'lsp-treemacs-references t)
:desc "Symbols" "S" #'lsp-treemacs-symbols)
:desc "Symbols" "S" #'lsp-treemacs-symbols
:desc "LSP" "l" #'+default/lsp-command-map
:desc "LSP Rename" "r" #'lsp-rename)
:desc "LSP Rename" "r" #'lsp-rename))
(:when (modulep! :tools lsp +eglot)
:desc "LSP Execute code action" "a" #'eglot-code-actions
:desc "LSP Rename" "r" #'eglot-rename

33
modules/config/default/config.el
View file

@ -458,6 +458,39 @@ Continues comments if executed from a commented line. Consults
'(evil-ex-completion-map)))
"C-s" command))
(map! :when (modulep! :completion corfu)
:after corfu
(:map corfu-map
"C-S-s" #'+corfu-move-to-minibuffer
"C-p" #'corfu-previous
"C-n" #'corfu-next
"S-TAB" #'corfu-previous
[backtab] #'corfu-previous
"TAB" #'corfu-next
[tab] #'corfu-next))
(let ((cmds-ret
`(menu-item "Insert completion DWIM" corfu-insert
:filter ,(lambda (cmd)
(interactive)
(cond ((null +corfu-want-ret-to-confirm)
(corfu-quit)
nil)
((eq +corfu-want-ret-to-confirm 'minibuffer)
(funcall-interactively cmd)
nil)
((and (or (not (minibufferp nil t))
(eq +corfu-want-ret-to-confirm t))
(>= corfu--index 0))
cmd)
((or (not (minibufferp nil t))
(eq +corfu-want-ret-to-confirm t))
nil)
(t cmd))))))
(map! :when (modulep! :completion corfu)
:map corfu-map
:gi [return] cmds-ret
:gi "RET" cmds-ret))
;; 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
;; it will ignore comments+trailing whitespace before jumping to eol.

5
modules/tools/lsp/+lsp.el
View file

@ -138,8 +138,11 @@ server getting expensively restarted when reverting buffers."
" "))
(add-to-list 'global-mode-string
'(t (:eval lsp-modeline-icon))
'append))))))
'append)))))
(when (modulep! :completion corfu)
(setq lsp-completion-provider :none)
(add-hook 'lsp-mode-hook #'lsp-completion-mode)))
(use-package! lsp-ui
:hook (lsp-mode . lsp-ui-mode)

1
templates/init.example.el
View file

@ -22,6 +22,7 @@
:completion
company ; the ultimate code completion backend
;;(corfu +orderless) ; complete with cap(f), cape and a flying feather!
;;helm ; the *other* search engine for love and life
;;ido ; the other *other* search engine...
;;ivy ; a search engine for love and life