dotemacs

My Emacs configuration
git clone git://git.entf.net/dotemacs
Log | Files | Refs | LICENSE

README.org (31323B)


      1 #+title: corfu.el - COmpletion in Region FUnction
      2 #+author: Daniel Mendler
      3 #+language: en
      4 #+export_file_name: corfu.texi
      5 #+texinfo_dir_category: Emacs misc features
      6 #+texinfo_dir_title: Corfu: (corfu).
      7 #+texinfo_dir_desc: COmpletion in Region FUnction
      8 
      9 #+html: <a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a>
     10 #+html: <a href="https://elpa.gnu.org/packages/corfu.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/corfu.svg"/></a>
     11 #+html: <a href="https://elpa.gnu.org/devel/corfu.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/corfu.svg"/></a>
     12 #+html: <a href="https://melpa.org/#/corfu"><img alt="MELPA" src="https://melpa.org/packages/corfu-badge.svg"/></a>
     13 #+html: <a href="https://stable.melpa.org/#/corfu"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/corfu-badge.svg"/></a>
     14 
     15 Corfu enhances in-buffer completion with a small completion popup. The current
     16 candidates are shown in a popup below or above the point. The candidates can be
     17 selected by moving up and down. Corfu is the minimalistic in-buffer completion
     18 counterpart of the [[https://github.com/minad/vertico][Vertico]] minibuffer UI.
     19 
     20 Corfu is a small package, which relies on the Emacs completion facilities and
     21 concentrates on providing a polished completion UI. In-buffer completion UIs in
     22 Emacs can hook into ~completion-in-region~, which implements the interaction with
     23 the user. Completions at point are either provided by commands like
     24 ~dabbrev-completion~ or by pluggable backends (~completion-at-point-functions~,
     25 Capfs) and are then passed to ~completion-in-region~. Many programming, text and
     26 shell major modes implement a Capf. Corfu does not include its own completion
     27 backends. The Emacs built-in Capfs and the Capfs provided by third-party
     28 programming language packages are often sufficient. Additional Capfs and
     29 completion utilities are provided by the [[https://github.com/minad/cape][Cape]] package.
     30 
     31 *NOTE*: Corfu uses child frames to show the popup and falls back to the default
     32 setting of the ~completion-in-region-function~ on non-graphical displays. If you
     33 want to use Corfu in the terminal, install the package [[https://codeberg.org/akib/emacs-corfu-terminal][corfu-terminal]], which
     34 provides an alternative overlay-based display.
     35 
     36 #+html: <img src="https://github.com/minad/corfu/blob/screenshots/light.png?raw=true">
     37 
     38 #+html: <img src="https://github.com/minad/corfu/blob/screenshots/dark.png?raw=true">
     39 
     40 #+html: <img src="https://github.com/minad/corfu/blob/screenshots/popupinfo-light.png?raw=true">
     41 
     42 #+html: <img src="https://github.com/minad/corfu/blob/screenshots/popupinfo-dark.png?raw=true">
     43 
     44 #+toc: headlines 8
     45 
     46 * Features
     47 
     48 - Timer-based auto-completions (/off/ by default, set ~corfu-auto~).
     49 - Popup display with scrollbar indicator and arrow key navigation.
     50 - The popup can be summoned explicitly by pressing =TAB= at any time.
     51 - The current candidate is inserted with =TAB= and selected with =RET=.
     52 - Candidate sorting by prefix, string length and alphabetically.
     53 - The selected candidate is previewed (configurable via ~corfu-preview-current~).
     54 - The selected candidate is automatically committed on further input by default.
     55   (configurable via ~corfu-preview-current~).
     56 - Supports the [[https://github.com/oantolin/orderless][Orderless]] completion style. The filter string can contain
     57   arbitrary characters, after inserting a space via =M-SPC= (configurable via
     58   ~corfu-quit-at-boundary~ and ~corfu-separator~).
     59 - Lazy completion candidate highlighting for performance.
     60 - Support for candidate annotations (=annotation-function=, =affixation-function=).
     61 - Deprecated candidates are displayed as crossed out.
     62 - Icons can be provided by an external package via margin formatter functions.
     63 - Rich set of extensions: Quick keys, Index keys, Sorting by history, Candidate
     64   documentation in echo area, popup or separate buffer.
     65 
     66 * Installation
     67 
     68 Corfu is available from [[https://elpa.gnu.org/packages/corfu.html][GNU ELPA]]. You can install it directly via =M-x package-install RET corfu RET=.
     69 After installation, activate the global minor mode with =M-x global-corfu-mode RET=.
     70 Set the variable ~corfu-auto~ to t in order to enable auto completion. For manual
     71 completion press =M-TAB= (or =TAB=) within a buffer.
     72 
     73 * Key bindings
     74 
     75 Corfu uses a transient keymap ~corfu-map~ which is active while the popup is
     76 shown. The keymap defines the following remappings of fundamental commands and
     77 bindings:
     78 
     79 | Binding/Remapping        | Corfu command            |
     80 |--------------------------+--------------------------|
     81 | ~move-beginning-of-line~   | ~corfu-prompt-beginning~   |
     82 | ~move-end-of-line~         | ~corfu-prompt-end~         |
     83 | ~beginning-of-buffer~      | ~corfu-first~              |
     84 | ~end-of-buffer~            | ~corfu-last~               |
     85 | ~scroll-down-command~      | ~corfu-scroll-down~        |
     86 | ~scroll-up-command~        | ~corfu-scroll-up~          |
     87 | ~next-line~, =down=, =M-n=     | ~corfu-next~               |
     88 | ~previous-line~, =up=, =M-p=   | ~corfu-previous~           |
     89 | ~completion-at-point~, =TAB= | ~corfu-complete~           |
     90 | =M-TAB=                    | ~corfu-expand~             |
     91 | =RET=                      | ~corfu-insert~             |
     92 | =M-g=                      | ~corfu-info-location~      |
     93 | =M-h=                      | ~corfu-info-documentation~ |
     94 | =M-SPC=                    | ~corfu-insert-separator~   |
     95 | =C-g=                      | ~corfu-quit~               |
     96 | ~keyboard-escape-quit~     | ~corfu-reset~              |
     97 
     98 * Configuration
     99 
    100 In order to configure Corfu and other packages in your init.el, you may want to
    101 use ~use-package~. Corfu is flexibly customizable via ~corfu-*~ customization
    102 variables, such that you can adapt it precisely to your requirements. However in
    103 order to quickly try out the Corfu completion package, it should be sufficient
    104 to activate ~global-corfu-mode~. You can experiment with manual completion for
    105 example in an Elisp buffer or in an Eshell or Shell buffer. For auto completion,
    106 set ~corfu-auto~ to t before turning on ~global-corfu-mode~.
    107 
    108 Here is an example configuration:
    109 
    110 #+begin_src emacs-lisp
    111 (use-package corfu
    112   ;; Optional customizations
    113   ;; :custom
    114   ;; (corfu-cycle t)                ;; Enable cycling for `corfu-next/previous'
    115   ;; (corfu-auto t)                 ;; Enable auto completion
    116   ;; (corfu-separator ?\s)          ;; Orderless field separator
    117   ;; (corfu-quit-at-boundary nil)   ;; Never quit at completion boundary
    118   ;; (corfu-quit-no-match nil)      ;; Never quit, even if there is no match
    119   ;; (corfu-preview-current nil)    ;; Disable current candidate preview
    120   ;; (corfu-preselect 'prompt)      ;; Preselect the prompt
    121   ;; (corfu-on-exact-match nil)     ;; Configure handling of exact matches
    122   ;; (corfu-scroll-margin 5)        ;; Use scroll margin
    123 
    124   ;; Enable Corfu only for certain modes.
    125   ;; :hook ((prog-mode . corfu-mode)
    126   ;;        (shell-mode . corfu-mode)
    127   ;;        (eshell-mode . corfu-mode))
    128 
    129   ;; Recommended: Enable Corfu globally.  This is recommended since Dabbrev can
    130   ;; be used globally (M-/).  See also the customization variable
    131   ;; `global-corfu-modes' to exclude certain modes.
    132   :init
    133   (global-corfu-mode))
    134 
    135 ;; A few more useful configurations...
    136 (use-package emacs
    137   :init
    138   ;; TAB cycle if there are only few candidates
    139   ;; (setq completion-cycle-threshold 3)
    140 
    141   ;; Enable indentation+completion using the TAB key.
    142   ;; `completion-at-point' is often bound to M-TAB.
    143   (setq tab-always-indent 'complete)
    144 
    145   ;; Emacs 30 and newer: Disable Ispell completion function. As an alternative,
    146   ;; try `cape-dict'.
    147   (setq text-mode-ispell-word-completion nil)
    148 
    149   ;; Emacs 28 and newer: Hide commands in M-x which do not apply to the current
    150   ;; mode.  Corfu commands are hidden, since they are not used via M-x. This
    151   ;; setting is useful beyond Corfu.
    152   (setq read-extended-command-predicate #'command-completion-default-include-p))
    153 #+end_src
    154 
    155 Dabbrev completion is based on =completion-in-region= and can be used with Corfu.
    156 You may want to swap the =dabbrev-completion= with the =dabbrev-expand= key for
    157 easier access, if you prefer completion. Also take a look at the =cape-dabbrev=
    158 completion at point function provided by my [[https://github.com/minad/cape][Cape]] package.
    159 
    160 #+begin_src emacs-lisp
    161 ;; Use Dabbrev with Corfu!
    162 (use-package dabbrev
    163   ;; Swap M-/ and C-M-/
    164   :bind (("M-/" . dabbrev-completion)
    165          ("C-M-/" . dabbrev-expand))
    166   :config
    167   (add-to-list 'dabbrev-ignored-buffer-regexps "\\` ")
    168   ;; Since 29.1, use `dabbrev-ignored-buffer-regexps' on older.
    169   (add-to-list 'dabbrev-ignored-buffer-modes 'doc-view-mode)
    170   (add-to-list 'dabbrev-ignored-buffer-modes 'pdf-view-mode))
    171 #+end_src
    172 
    173 If you start to configure the package more deeply, I recommend to give the
    174 Orderless completion style a try for filtering. Orderless completion is
    175 different from the familiar prefix TAB completion. Corfu can be used with the
    176 default completion styles. The use of Orderless is not a necessity.
    177 
    178 #+begin_src emacs-lisp
    179 ;; Optionally use the `orderless' completion style.
    180 (use-package orderless
    181   :init
    182   ;; Configure a custom style dispatcher (see the Consult wiki)
    183   ;; (setq orderless-style-dispatchers '(+orderless-dispatch)
    184   ;;       orderless-component-separator #'orderless-escapable-split-on-space)
    185   (setq completion-styles '(orderless basic)
    186         completion-category-defaults nil
    187         completion-category-overrides '((file (styles partial-completion)))))
    188 #+end_src
    189 
    190 The =basic= completion style is specified as fallback in addition to =orderless= in
    191 order to ensure that completion commands which rely on dynamic completion
    192 tables, e.g., ~completion-table-dynamic~ or ~completion-table-in-turn~, work
    193 correctly. See =+orderless-dispatch= in the [[https://github.com/minad/consult/wiki][Consult wiki]] for an advanced Orderless
    194 style dispatcher. Additionally enable =partial-completion= for file path
    195 expansion. =partial-completion= is important for file wildcard support. Multiple
    196 files can be opened at once with =find-file= if you enter a wildcard. You may also
    197 give the =initials= completion style a try.
    198 
    199 See also the [[https://github.com/minad/corfu/wiki][Corfu Wiki]] and the [[https://github.com/minad/cape][Cape manual]] for additional Capf configuration
    200 tips. For more general documentation read the chapter about completion in the
    201 [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Completion.html][Emacs manual]]. If you want to create your own Capfs, you can find documentation
    202 about completion in the [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html][Elisp manual]].
    203 
    204 ** Auto completion
    205 
    206 Auto completion is disabled by default, but can be enabled by setting ~corfu-auto~
    207 to t. Furthermore you may want to configure Corfu to quit completion eagerly,
    208 such that the completion popup stays out of your way when it appeared
    209 unexpectedly.
    210 
    211 #+begin_src emacs-lisp
    212 ;; Enable auto completion and configure quitting
    213 (setq corfu-auto t
    214       corfu-quit-no-match 'separator) ;; or t
    215 #+end_src
    216 
    217 I suggest to experiment with the various settings and key bindings to find a
    218 configuration which works for you. There is no one perfect configuration which
    219 fits all. Some people like auto completion, some like manual completion, some
    220 want to cycle with TAB and some with the arrow keys.
    221 
    222 In case you like auto completion settings, where the completion popup appears
    223 immediately, better use a cheap completion style like =basic=, which performs
    224 prefix filtering. In this case Corfu completion should still be fast in buffers
    225 with efficient completion backends. You can try the following settings in an
    226 Elisp buffer or the Emacs scratch buffer. Note that such settings can slow down
    227 Emacs due to the high load on the Lisp runtime and garbage collector.
    228 
    229 #+begin_src emacs-lisp
    230 (setq-local corfu-auto        t
    231             corfu-auto-delay  0 ;; TOO SMALL - NOT RECOMMENDED
    232             corfu-auto-prefix 1 ;; TOO SMALL - NOT RECOMMENDED
    233             completion-styles '(basic))
    234 #+end_src
    235 
    236 If you want to combine fast prefix filtering and Orderless filtering you can
    237 still do that by defining a custom Orderless completion style via
    238 =orderless-define-completion-style=. We use a custom style dispatcher, which
    239 enables efficient prefix filtering for input shorter than 4 characters. Note
    240 that such a setup is advanced. Please refer to the Orderless documentation and
    241 source code for further details.
    242 
    243 #+begin_src emacs-lisp
    244 (defun orderless-fast-dispatch (word index total)
    245   (and (= index 0) (= total 1) (length< word 4)
    246        (cons 'orderless-literal-prefix word))))
    247 
    248 (orderless-define-completion-style orderless-fast
    249   (orderless-style-dispatchers '(orderless-fast-dispatch))
    250   (orderless-matching-styles '(orderless-literal orderless-regexp)))
    251 
    252 (setq-local corfu-auto        t
    253             corfu-auto-delay  0 ;; TOO SMALL - NOT RECOMMENDED
    254             corfu-auto-prefix 1 ;; TOO SMALL - NOT RECOMMENDED
    255             completion-styles '(orderless-fast basic))
    256 #+end_src
    257 
    258 ** Completing in the minibuffer
    259 
    260 Corfu can be used for completion in the minibuffer, since it relies on child
    261 frames to display the candidates. The Corfu popup can be shown even if it
    262 doesn't fully fit inside the minibuffer.
    263 
    264 By default, ~global-corfu-mode~ does not activate ~corfu-mode~ in the minibuffer, to
    265 avoid interference with specialised minibuffer completion UIs like Vertico or
    266 Mct. However you may still want to enable Corfu completion for commands like ~M-:~
    267 (~eval-expression~) or ~M-!~ (~shell-command~), which read from the minibuffer. In
    268 order to detect minibuffers with completion we check if the variable
    269 ~completion-at-point-functions~ is set locally.
    270 
    271 #+begin_src emacs-lisp
    272 (defun corfu-enable-in-minibuffer ()
    273   "Enable Corfu in the minibuffer."
    274   (when (local-variable-p 'completion-at-point-functions)
    275     ;; (setq-local corfu-auto nil) ;; Enable/disable auto completion
    276     (setq-local corfu-echo-delay nil ;; Disable automatic echo and popup
    277                 corfu-popupinfo-delay nil)
    278     (corfu-mode 1)))
    279 (add-hook 'minibuffer-setup-hook #'corfu-enable-in-minibuffer)
    280 #+end_src
    281 
    282 This is not recommended, but one can also enable Corfu more generally for every
    283 minibuffer, as long as no completion UI is active. In the following example we
    284 check for Mct and Vertico. Furthermore we ensure that Corfu is not enabled if a
    285 password is read from the minibuffer.
    286 
    287 #+begin_src emacs-lisp
    288 (defun corfu-enable-always-in-minibuffer ()
    289   "Enable Corfu in the minibuffer if Vertico/Mct are not active."
    290   (unless (or (bound-and-true-p mct--active)
    291               (bound-and-true-p vertico--input)
    292               (eq (current-local-map) read-passwd-map))
    293     ;; (setq-local corfu-auto nil) ;; Enable/disable auto completion
    294     (setq-local corfu-echo-delay nil ;; Disable automatic echo and popup
    295                 corfu-popupinfo-delay nil)
    296     (corfu-mode 1)))
    297 (add-hook 'minibuffer-setup-hook #'corfu-enable-always-in-minibuffer 1)
    298 #+end_src
    299 
    300 ** Completing in the Eshell or Shell
    301 
    302 When completing in the Eshell I recommend conservative local settings without
    303 auto completion, such that the completion behavior is similar to widely used
    304 shells like Bash, Zsh or Fish.
    305 
    306 #+begin_src emacs-lisp
    307 (add-hook 'eshell-mode-hook
    308           (lambda ()
    309             (setq-local corfu-auto nil)
    310             (corfu-mode)))
    311 #+end_src
    312 
    313 When pressing =RET= while the Corfu popup is visible, the ~corfu-insert~ command
    314 will be invoked. This command does inserts the currently selected candidate, but
    315 it does not send the prompt input to Eshell or the Comint process. Therefore you
    316 often have to press =RET= twice which feels like an unnecessary double
    317 confirmation. Fortunately it is easy to improve this! In my configuration I
    318 define the advice ~corfu-send-shell~ which sends the candidate after insertion.
    319 
    320 #+begin_src emacs-lisp
    321 (defun corfu-send-shell (&rest _)
    322   "Send completion candidate when inside comint/eshell."
    323   (cond
    324    ((and (derived-mode-p 'eshell-mode) (fboundp 'eshell-send-input))
    325     (eshell-send-input))
    326    ((and (derived-mode-p 'comint-mode)  (fboundp 'comint-send-input))
    327     (comint-send-input))))
    328 
    329 (advice-add #'corfu-insert :after #'corfu-send-shell)
    330 #+end_src
    331 
    332 Shell completion uses the flexible Pcomplete mechanism internally, which allows
    333 you to program the completions per shell command. If you want to know more, look
    334 into this [[https://www.masteringemacs.org/article/pcomplete-context-sensitive-completion-emacs][blog post]], which shows how to configure Pcomplete for git commands.
    335 Since Emacs 29, Pcomplete offers the =pcomplete-from-help= function which parses
    336 the ~--help~ output of a command and produces completions for command line
    337 options.
    338 
    339 Pcomplete has a few bugs on Emacs 28 and older. We can work around the issues
    340 with the [[https://github.com/minad/cape][Cape]] library (Completion at point extensions). Cape provides wrappers
    341 which sanitize the Pcomplete function. If you use Emacs 28 or older installing
    342 these advices is recommended such that Pcomplete works properly. On Emacs 29 the
    343 advices should not be necessary anymore, since most relevant bugs have been
    344 fixed. I therefore recommend to avoid the advices on Emacs 29 and eventually
    345 report any remaining Pcomplete issues upstream.
    346 
    347 #+begin_src emacs-lisp
    348 ;; The advices are only needed on Emacs 28 and older.
    349 (when (< emacs-major-version 29)
    350   ;; Silence the pcomplete capf. Hide errors or messages.
    351   (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-silent)
    352 
    353   ;; Ensure that pcomplete does not write to the buffer and behaves as a
    354   ;; `completion-at-point-function' without side-effects.
    355   (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-purify))
    356 #+end_src
    357 
    358 ** Orderless completion
    359 
    360 [[https://github.com/oantolin/orderless][Orderless]] is an advanced completion style that supports multi-component search
    361 filters separated by a configurable character (space, by default). Normally,
    362 entering characters like space which lie outside the completion region
    363 boundaries (words, typically) causes Corfu to quit. This behavior is helpful
    364 with auto-completion, which may pop-up when not desired, e.g. on entering a new
    365 variable name. Just keep typing and Corfu will get out of the way.
    366 
    367 But orderless search terms can contain arbitrary characters; they are also
    368 interpreted as regular expressions. To use orderless, set ~corfu-separator~ (a
    369 space, by default) to the primary character of your orderless component
    370 separator.
    371 
    372 Then, when a new orderless component is desired, use =M-SPC=
    373 (~corfu-insert-separator~) to enter the first component separator in the input,
    374 and arbitrary orderless search terms and new separators can be entered
    375 thereafter.
    376 
    377 To treat the entire input as Orderless input, you can set the customization
    378 option ~corfu-quit-at-boundary~ to nil. This disables the predicate which checks
    379 if the current completion boundary has been left. In contrast, if you always
    380 want to quit at the boundary, set ~corfu-quit-at-boundary~ to t. By default
    381 ~corfu-quit-at-boundary~ is set to ~separator~ which quits at completion boundaries
    382 as long as no separator has been inserted with ~corfu-insert-separator~.
    383 
    384 Finally, there exists the user option ~corfu-quit-no-match~ which is set to
    385 =separator= by default. With this setting Corfu stays alive as soon as you start
    386 advanced filtering with a ~corfu-separator~ even if there are no matches, for
    387 example due to a typo. As long as no separator character has been inserted with
    388 ~corfu-insert-separator~, Corfu will still quit if there are no matches. This
    389 ensures that the Corfu popup goes away quickly if completion is not possible.
    390 
    391 In the following we show two configurations, one which works best with auto
    392 completion and one which may work better with manual completion if you prefer to
    393 always use =SPC= to separate the Orderless components.
    394 
    395  #+begin_src emacs-lisp
    396 ;; Auto completion example
    397 (use-package corfu
    398   :custom
    399   (corfu-auto t)          ;; Enable auto completion
    400   ;; (corfu-separator ?_) ;; Set to orderless separator, if not using space
    401   :bind
    402   ;; Another key binding can be used, such as S-SPC.
    403   ;; (:map corfu-map ("M-SPC" . corfu-insert-separator))
    404   :init
    405   (global-corfu-mode))
    406 
    407 ;; Manual completion example
    408 (use-package corfu
    409   :custom
    410   ;; (corfu-separator ?_) ;; Set to orderless separator, if not using space
    411   :bind
    412   ;; Configure SPC for separator insertion
    413   (:map corfu-map ("SPC" . corfu-insert-separator))
    414   :init
    415   (global-corfu-mode))
    416 #+end_src
    417 
    418 ** TAB-only completion
    419 
    420 By default, Corfu steals both the ~RET~ and ~TAB~ keys, when the Corfu popup is
    421 open. This can feel intrusive, in particular in combination with auto
    422 completion. ~RET~ may accidentally commit an automatically selected candidate,
    423 while you actually wanted to start a new line. As an alternative we can unbind
    424 the ~RET~ key completely from ~corfu-map~ or reserve the ~RET~ key only in shell
    425 modes.
    426 
    427 #+begin_src emacs-lisp
    428 ;; TAB-only configuration
    429 (use-package corfu
    430   :custom
    431   (corfu-auto t)               ;; Enable auto completion
    432   (corfu-preselect 'directory) ;; Select the first candidate, except for directories
    433 
    434   ;; Free the RET key for less intrusive behavior.
    435   :bind
    436   (:map corfu-map
    437         ;; Option 1: Unbind RET completely
    438         ;;; ("RET" . nil)
    439         ;; Option 2: Use RET only in shell modes
    440         ("RET" . (menu-item "" nil :filter corfu-insert-shell-filter)))
    441 
    442   :init
    443   (global-corfu-mode))
    444 
    445 (defun corfu-insert-shell-filter (&optional _)
    446   "Insert completion candidate and send when inside comint/eshell."
    447   (when (or (derived-mode-p 'eshell-mode) (derived-mode-p 'comint-mode))
    448     (lambda ()
    449       (interactive)
    450       (corfu-insert)
    451       ;; `corfu-send-shell' was defined above
    452       (corfu-send-shell))))
    453 #+end_src
    454 
    455 ** TAB-and-Go completion
    456 
    457 You may be interested in configuring Corfu in TAB-and-Go style. Pressing TAB
    458 moves to the next candidate and further input will then commit the selection.
    459 Note that further input will not expand snippets or templates, which may not be
    460 desired but which leads overall to a more predictable behavior. In order to
    461 force snippet expansion, confirm a candidate explicitly with ~RET~.
    462 
    463 #+begin_src emacs-lisp
    464 (use-package corfu
    465   ;; TAB-and-Go customizations
    466   :custom
    467   (corfu-cycle t)           ;; Enable cycling for `corfu-next/previous'
    468   (corfu-preselect 'prompt) ;; Always preselect the prompt
    469 
    470   ;; Use TAB for cycling, default is `corfu-complete'.
    471   :bind
    472   (:map corfu-map
    473         ("TAB" . corfu-next)
    474         ([tab] . corfu-next)
    475         ("S-TAB" . corfu-previous)
    476         ([backtab] . corfu-previous))
    477 
    478   :init
    479   (global-corfu-mode))
    480 #+end_src
    481 
    482 ** Expanding to the common candidate prefix with TAB
    483 
    484 If you leave the default configuration of the completion styles, such that the
    485 ~basic~ completion style is still present, then pressing ~M-TAB~ (~corfu-expand~) will
    486 expand the current input to the common prefix of all completion candidates. In
    487 contrast, ~TAB~ (~corfu-complete~) behaves differently and expands input to the
    488 currently selected candidate.
    489 
    490 If you use the ~orderless~ completion style, then expansion works differently by
    491 default. Orderless only expands to single matching candidates, since due to its
    492 multi-component input, there does not necessarily exist an expansion to a common
    493 candidate prefix. However it is possible to define a separate ~tab~ completion
    494 style. The ~tab~ completion style will only take over ~TAB~ completion (if prefix
    495 expansion is possible), but besides that won't affect Orderless candidate
    496 filtering.
    497 
    498 #+begin_src emacs-lisp
    499 (add-to-list 'completion-styles-alist
    500              '(tab completion-basic-try-completion ignore
    501                "Completion style which provides TAB completion only."))
    502 (setq completion-styles '(tab orderless basic)))
    503 #+end_src
    504 
    505 ** Transfer completion to the minibuffer
    506 
    507 Sometimes it is useful to transfer the Corfu completion session to the
    508 minibuffer, since the minibuffer offers richer interaction features. In
    509 particular, [[https://github.com/oantolin/embark][Embark]] is available in the minibuffer, such that you can act on the
    510 candidates or export/collect the candidates to a separate buffer. We could add
    511 Corfu support to Embark in the future, such that export or collect is possible
    512 directly from Corfu. Nevertheless, the ability to transfer the Corfu completion
    513 to the minibuffer is even more powerful, since further completion is possible.
    514 
    515 The command ~corfu-move-to-minibuffer~ is defined here in terms of
    516 ~consult-completion-in-region~, which uses the minibuffer completion UI via
    517 ~completing-read~.
    518 
    519 #+begin_src emacs-lisp
    520 (defun corfu-move-to-minibuffer ()
    521   (interactive)
    522   (pcase completion-in-region--data
    523     (`(,beg ,end ,table ,pred ,extras)
    524      (let ((completion-extra-properties extras)
    525            completion-cycle-threshold completion-cycling)
    526        (consult-completion-in-region beg end table pred)))))
    527 (keymap-set corfu-map "M-m" #'corfu-move-to-minibuffer)
    528 (add-to-list 'corfu-continue-commands #'corfu-move-to-minibuffer)
    529 #+end_src
    530 
    531 * Extensions
    532 :properties:
    533 :custom_id: extensions
    534 :end:
    535 
    536 We maintain small extension packages to Corfu in this repository in the
    537 subdirectory [[https://github.com/minad/corfu/tree/main/extensions][extensions/]]. The extensions are installed together with Corfu if
    538 you pull the package from ELPA. The extensions are inactive by default and can
    539 be enabled manually if desired. Furthermore it is possible to install all of the
    540 files separately, both ~corfu.el~ and the ~corfu-*.el~ extensions. Currently the
    541 following extensions come with the Corfu ELPA package:
    542 
    543 - [[https://github.com/minad/corfu/blob/main/extensions/corfu-echo.el][corfu-echo]]: =corfu-echo-mode= displays a brief candidate documentation in the
    544   echo area.
    545 - [[https://github.com/minad/corfu/blob/main/extensions/corfu-history.el][corfu-history]]: =corfu-history-mode= remembers selected candidates and sorts the
    546   candidates by their history position.
    547 - [[https://github.com/minad/corfu/blob/main/extensions/corfu-indexed.el][corfu-indexed]]: =corfu-indexed-mode= allows you to select indexed candidates with
    548   prefix arguments.
    549 - [[https://github.com/minad/corfu/blob/main/extensions/corfu-info.el][corfu-info]]: Actions to access the candidate location and documentation.
    550 - [[https://github.com/minad/corfu/blob/main/extensions/corfu-popupinfo.el][corfu-popupinfo]]: Display candidate documentation or source in a popup next to
    551   the candidate menu.
    552 - [[https://github.com/minad/corfu/blob/main/extensions/corfu-quick.el][corfu-quick]]: Commands to select using Avy-style quick keys.
    553 
    554 See the Commentary of those files for configuration details.
    555 
    556 * Complementary packages
    557 
    558 Corfu works well together with all packages providing code completion via the
    559 ~completion-at-point-functions~. Many modes and packages already provide a Capf
    560 out of the box. Nevertheless you may want to look into complementary packages to
    561 enhance your setup.
    562 
    563 - [[https://codeberg.org/akib/emacs-corfu-terminal][corfu-terminal]]: The corfu-terminal package provides an overlay-based display
    564   for Corfu, such that you can use Corfu in terminal Emacs.
    565 
    566 - [[https://code.bsdgeek.org/adam/corfu-candidate-overlay][corfu-candidate-overlay]]: Shows as-you-type auto-suggestion candidate overlay
    567   with a visual indication of whether there are many or exactly one candidate
    568   available (works only with =corfu-auto= disabled).
    569 
    570 - [[https://github.com/oantolin/orderless][Orderless]]: Corfu supports completion styles, including the advanced =orderless=
    571   completion style, where the filter expressions are separated by spaces or
    572   another character (see ~corfu-separator~).
    573 
    574 - [[https://github.com/minad/cape][Cape]]: Provides additional Capf backends and =completion-in-region= commands.
    575   Among others, the package supplies the file completion backend =cape-file= and
    576   the Dabbrev backend =cape-dabbrev=. Cape provides the ~cape-company-to-capf~
    577   adapter to reuse Company backends in Corfu.
    578 
    579 - [[https://github.com/LuigiPiucco/nerd-icons-corfu][nerd-icons-corfu]], [[https://github.com/jdtsmith/kind-icon][kind-icon]]: Icons are supported by Corfu via external
    580   packages. The nerd-icons-corfu package relies on the Nerd icon font, which is
    581   even supported on terminal, while kind-icon uses SVGs from monochromatic icon
    582   sets.
    583 
    584 - [[https://github.com/minad/tempel][Tempel]]: Tiny template/snippet package with templates in Lisp syntax, which
    585   can be used in conjunction with Corfu.
    586 
    587 - [[https://github.com/minad/vertico][Vertico]]: You may also want to look into my Vertico package. Vertico is the
    588   minibuffer completion counterpart of Corfu.
    589 
    590 * Alternatives
    591 
    592 - [[https://github.com/company-mode/company-mode][Company]]: Company is a widely used and mature completion package, which
    593   implements a similar UI as Corfu. While Corfu relies exclusively on the
    594   standard Emacs completion API (Capfs), Company defines its own API for the
    595   backends. Company includes its own completion backends, following its own API,
    596   which are incompatible with the Emacs completion infrastructure. Company
    597   provides an adapter ~company-capf~ to handle Capfs as a Company backend. As a
    598   result of this design, Company is a more complex package than Corfu. Company
    599   by default uses overlays for the popup in contrast to the child frames used by
    600   Corfu. Overall both packages work well, but Company integrates less tightly
    601   with Emacs. The ~completion-styles~ support is more limited and the
    602   ~completion-at-point~ command and the ~completion-in-region~ function do not
    603   invoke Company.
    604 
    605 - [[https://github.com/minad/consult][consult-completion-in-region]]: The Consult package provides the function
    606   ~consult-completion-in-region~ which can be set as ~completion-in-region-function~
    607   such that it handles ~completion-at-point~. The function works by transferring
    608   the in-buffer completion to the minibuffer. In the minibuffer, the minibuffer
    609   completion UI, for example [[https://github.com/minad/vertico][Vertico]] takes over. If you prefer to perform all
    610   your completions in the minibuffer ~consult-completion-in-region~ is your best
    611   option.
    612 
    613 * Debugging Corfu
    614 
    615 When you observe an error in the =corfu--post-command= post command hook, you
    616 should install an advice to enforce debugging. This allows you to obtain a stack
    617 trace in order to narrow down the location of the error. The reason is that post
    618 command hooks are automatically disabled (and not debugged) by Emacs. Otherwise
    619 Emacs would become unusable, given that the hooks are executed after every
    620 command.
    621 
    622 #+begin_src emacs-lisp
    623 (setq debug-on-error t)
    624 
    625 (defun force-debug (func &rest args)
    626   (condition-case e
    627       (apply func args)
    628     ((debug error) (signal (car e) (cdr e)))))
    629 
    630 (advice-add #'corfu--post-command :around #'force-debug)
    631 #+end_src
    632 
    633 When Capfs do not yield the expected result you can use ~cape-capf-debug~ to add
    634 debug messages to a Capf. The Capf will then produce a completion log in the
    635 messages buffer.
    636 
    637 #+begin_src emacs-lisp
    638 (setq completion-at-point-functions (list (cape-capf-debug #'cape-dict)))
    639 #+end_src
    640 
    641 * Contributions
    642 
    643 Since this package is part of [[https://elpa.gnu.org/packages/corfu.html][GNU ELPA]] contributions require a copyright
    644 assignment to the FSF.