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