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