module: add :completion corfu
This commit's primary goal is allowing use of [minad/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 [minad/cape](https://github.com/minad/cape) capfs for certain modes. Other optional or miscellaneous features include: - Support for displaying the completion's documentation on a secondary popup; - Support for terminal display if :os tty; - Support for icons if +icons; - Support for tab-and-go completion if +tng;
This commit is contained in:
Luigi Sartor Piucco
parent
180ffd3fa8
commit
ee1ebab197
5 changed files with 295 additions and 1 deletions
155
modules/completion/corfu/README.org
Normal file
155
modules/completion/corfu/README.org
Normal file
|
|
@ -0,0 +1,155 @@
|
|||
#+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.
|
||||
|
||||
** Maintainers
|
||||
- [[doom-user:][@LuigiPiucco]]
|
||||
|
||||
[[doom-contrib-maintainer:][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
|
||||
[[kbd:][TAB]]. When Corfu is active, [[kbd:][TAB]] and [[kbd:][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).
|
||||
|
||||
** 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
|
||||
|
||||
** Code completion
|
||||
By default, completion gets triggered after typing 2 non-space consecutive
|
||||
characters, or by means of the [[kbd:][C-SPC]] keybinding at any moment. While the popup
|
||||
is visible, the following relevant keys are available:
|
||||
|
||||
| Keybind | Description |
|
||||
|----------+------------------------------------------------------------------|
|
||||
| [[kbd:][<down>]] | Go to next candidate |
|
||||
| [[kbd:][<up>]] | Go to previous candidate |
|
||||
| [[kbd:][C-n]] | Go to next candidate |
|
||||
| [[kbd:][C-p]] | 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-n]] | Go to next doc line |
|
||||
| [[kbd:][C-S-p]] | 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 |
|
||||
| [[kbd:][C-h]] | Toggle documentation (if available) |
|
||||
| [[kbd:][M-m]] | Export to minibuffer (if [[doom-module::completion vertico]]) |
|
||||
| [[kbd:][M-S-j]] | (evil) Export to minibuffer (if [[doom-module::completion vertico]]) |
|
||||
| [[kbd:][RET]] | Insert candidate |
|
||||
| [[kbd:][SPC]] | (after wildcard) Reset completion |
|
||||
| [[kbd:][DEL]] | Reset completion |
|
||||
| [[kbd:][C-SPC]] | Complete (unless [[doom-module::completion corfu +tng]]) |
|
||||
| [[kbd:][C-SPC]] | (when completing) Insert separator DWIM (see below) |
|
||||
|
||||
If you prefer a [[kbd:][TAB]]-centric completion style, enable the [[doom-module::completion
|
||||
corfu +tng]] flag so that, instead, you trigger completion with [[kbd:][TAB]], getting the
|
||||
following additional binds:
|
||||
|
||||
| Keybind | Description |
|
||||
|---------+-----------------------------------------------|
|
||||
| [[kbd:][TAB]] | Complete |
|
||||
| [[kbd:][TAB]] | (when completing) Go to next candidate |
|
||||
| [[kbd:][S-TAB]] | (when completing) Go to previous candidate |
|
||||
|
||||
** 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 [[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.
|
||||
|
||||
Additionally, for users of evil and regular corfu style, [[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.
|
||||
|
||||
** 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: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.
|
||||
|
||||
** 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 of omitted. Also
|
||||
see ~add-hook!~'s documentation for additional ways to call it. ~add-hook~ only
|
||||
accepts the quoted arguments form above.
|
||||
|
||||
* 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