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