dot-doom/modules/completion/corfu/README.org

#+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 ::
  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-completion]] if [[doom-module::completion corfu +icons]]
- [[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 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. Snippets may also appear in the candidate list if available.

* 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-j]]      | (evil) Export to minibuffer (if [[doom-module::completion vertico]]) |
| [[kbd:][RET]]      | Insert candidate                                        |
| [[kbd:][SPC]]      | Quit autocompletion after a wildcard or pass-through    |
| [[kbd:][C-SPC]]    | (when completing) Insert separator (see below)          |
| [[kbd:][C-SPC]]    | Complete (unless [[doom-module::completion corfu +tng]])             |

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    |
| [[kbd:][DEL]]     | (when completing) Reset completion DWIM-style |

** 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 restarts completion, so that when typing sentences it doesn't
try to complete the whole sentence instead of just the word.

Furthermore, if you also have [[var:+orderless-wildcard-character]] set (by default
it's the comma key), then that character acts as a wildcard when typed
mid-completion.

** 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.
- [[var:+orderless-wildcard-character]] ::
  Used for fuzzy-matching corfu invocations as an escapable alternative to
  ~corfu-separator~. Defaults to comma.
- [[var:+cape-buffer-scanning-size-limit:]]  ::
    Sets the maximum buffer size to be scanned by ~cape-dabbrev~ and
  ~cape-lines~. Defaults to 1 MB. Set this if you are having performance
  problems using ~cape-dabbrev~.

** 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-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)))
#+end_src

DEPTH above is an integer between -100, 100, and defaults to 0 of ommited. 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?]]

If you have performance issues with ~cape-dabbrev~, the first thing I recommend
doing is looking at the list of buffers Dabbrev is scanning with:

#+begin_src emacs-lisp
(dabbrev--select-buffers) ; => (#<buffer README.org> #<buffer config.el<3>> #<buffer cape.el> ...)
(length (dabbrev--select-buffers)) ; => 37
#+end_src

and modifying ~dabbrev-ignored-buffer-regexps~ or ~dabbrev-ignored-buffer-modes~
accordingly.

* 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