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