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.