module: add :completion corfu
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
parent
85ce866953
commit
6949451b00
9 changed files with 422 additions and 8 deletions
229
modules/completion/corfu/README.org
Normal file
229
modules/completion/corfu/README.org
Normal 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue