├── .dir-locals.el ├── .gitignore ├── CHANGELOG.org ├── COPYING ├── README.md ├── README.org ├── doclicense.texi └── mct.el /.dir-locals.el: -------------------------------------------------------------------------------- 1 | ;;; Directory Local Variables 2 | ;;; For more information see (info "(emacs) Directory Variables") 3 | 4 | ((emacs-lisp-mode . ((indent-tabs-mode . nil)))) 5 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.elc 2 | *-autoloads.el 3 | *-pkg.el 4 | mct.info 5 | mct.texi -------------------------------------------------------------------------------- /CHANGELOG.org: -------------------------------------------------------------------------------- 1 | #+TITLE: Change log of the Minibuffer and Completions in Tandem (mct) 2 | #+AUTHOR: Protesilaos Stavrou 3 | #+EMAIL: info@protesilaos.com 4 | #+OPTIONS: ':nil toc:nil num:nil author:nil email:nil 5 | 6 | This document contains the release notes that are included in each 7 | tagged commit on the project's main git repository: 8 | . 9 | 10 | The newest release is at the top. For further details, please consult 11 | the manual: . 12 | 13 | * Version 1.0.0 on 2023-09-24 14 | :PROPERTIES: 15 | :CUSTOM_ID: h:64daac36-a953-46cf-bc12-81a0a99bf964 16 | :END: 17 | 18 | ** Resumption of MCT development 19 | :PROPERTIES: 20 | :CUSTOM_ID: h:39f6904b-a045-4539-aa66-76be822064f9 21 | :END: 22 | 23 | In April 2022, I announced that I was discontinuing the development of 24 | my ~mct~ package. At the time, Emacs 29 was gaining new MCT-like 25 | capabilities and I thought we would quickly reach a point where my 26 | package would be superseded by built-in functionality. The article I 27 | published at the time: 28 | . 29 | 30 | About a year later and after receiving questions about MCT, I decided 31 | to restart its development. This was done in light of the realisation 32 | that the built-in Emacs functionality was still not as opinionated as 33 | MCT. There are good reasons for this state of affairs, due to the 34 | legacy of this important User Interface element and Emacs' policy to 35 | not break stuff willy nilly. Still, the fact remains that MCT can fit 36 | in a very narrow niche for those who (i) like the built-in completions 37 | and (ii) appreciate a few extra niceties. What I wrote in March, 2023: 38 | . 39 | 40 | What does MCT offer that the built-in Emacs UI does not? In short: 41 | 42 | - MCT provides a facility for "live completions", to automatically 43 | update the =*Completions*= buffer given certain conditions. A 44 | number of user options control the specifics. 45 | 46 | - There are user options for a passlist and blocklist, which determine 47 | what should automatically display the =*Completions*= buffer and be 48 | live updated. The passlist and the blocklist can target individual 49 | commands, such as ~find-file~, as well as completion categories like 50 | ~buffer~. The manual includes a section with several known 51 | completion categories. 52 | 53 | To be clear: MCT builds on top of the built-in functionality and 54 | should not compete with it. Depending on my availability, I will try 55 | to prepare patches for emacs.git to see whether at least some features 56 | can be added directly to =mnibuffer.el= or related. 57 | 58 | ** MCT supports Emacs 29 or higher 59 | :PROPERTIES: 60 | :CUSTOM_ID: h:6ee9aea9-91f3-47cf-aab3-984fe9e23157 61 | :END: 62 | 63 | MCT is highly opinionated about how the completions should work. This 64 | applies to the presentation of the completion candidates as well as 65 | the behaviour of commands that cycle between the minibuffer and the 66 | =*Completions*=, treating the two as a contiguous space. In previous 67 | versions of Emacs, MCT could not work exactly as intended due to 68 | limitations in the underlying framework. For example, the variable 69 | ~completions-format~ gained the ~one-column~ value only in Emacs 28: 70 | Emacs 27 supported grid views which are not intuitive as a vertical 71 | list for up-down cycling between the candidates. 72 | 73 | To make things easier to maintain, MCT only works with Emacs 29 or 74 | higher. The ~1 year hiatus has hopefully given users enough time to 75 | assess their options. 76 | 77 | ** Deprecation of ~mct-region-mode~ 78 | :PROPERTIES: 79 | :CUSTOM_ID: h:bf50160c-07e9-4625-af0a-5142d79ed35b 80 | :END: 81 | 82 | For a while, MCT supported in-buffer completion via a minor mode that 83 | would add all the needed functionality. This was always problematic 84 | due to underlying constrains and is thus no longer supported. MCT is 85 | designed to work exclusively with the minibuffer, where the behaviour 86 | is more reliable. 87 | 88 | Nevertheless, users can still get an MCT-like experience with these 89 | settings, which affect the default UI (modify as you see fit): 90 | 91 | #+begin_src emacs-lisp 92 | ;; Define the small wrapper functions 93 | (defun my-mct-next-line-or-completion (n) 94 | "Select next completion or move to next line N times. 95 | Select the next completion if `completion-in-region-mode' is 96 | active and the Completions window is on display." 97 | (interactive "p") 98 | (if (and completion-in-region-mode (mct--get-completion-window)) 99 | (minibuffer-next-completion n) 100 | (next-line n))) 101 | 102 | (defun my-mct-previous-line-or-completion (n) 103 | "Select previous completion or move to previous line N times. 104 | Select the previous completion if `completion-in-region-mode' is 105 | active and the Completions window is on display." 106 | (interactive "p") 107 | (if (and completion-in-region-mode (mct--get-completion-window)) 108 | (minibuffer-previous-completion n) 109 | (previous-line n))) 110 | 111 | (defun my-mct-return-or-choose-completion (n) 112 | "Choose current completion or create N newlines. 113 | Choose the current completion if `completion-in-region-mode' is 114 | active and the Completions window is on display." 115 | (interactive "p") 116 | (if (and completion-in-region-mode (mct--get-completion-window)) 117 | (minibuffer-choose-completion) 118 | (newline n :interactive))) 119 | 120 | ;; Get the key bindings 121 | (let ((map completion-in-region-mode-map)) 122 | (define-key map (kbd "C-n") #'my-mct-next-line-or-completion) 123 | (define-key map (kbd "C-p") #'my-mct-previous-line-or-completion) 124 | (define-key map (kbd "RET") #'my-mct-return-or-choose-completion)) 125 | 126 | ;; Tweak the appearance 127 | (setq completions-format 'one-column) 128 | (setq completion-show-help nil) 129 | (setq completion-auto-help t) 130 | 131 | ;; Optionally, tweak the appearance further 132 | (setq completions-detailed t) 133 | (setq completion-show-inline-help nil) 134 | (setq completions-max-height 6) 135 | (setq completions-highlight-face 'completions-highlight) 136 | #+end_src 137 | 138 | ** The ~mct-minibuffer-mode~ is renamed to ~mct-mode~ 139 | :PROPERTIES: 140 | :CUSTOM_ID: h:d93fc6b9-3b21-4072-91d3-29a51d8f26f3 141 | :END: 142 | 143 | The ~mct-mode~ was the original name, which was later given the 144 | "minibuffer" specifier to disambiguate it from the aforementioned 145 | ~mct-region-mode~. With the latter gone, this qualification is no 146 | longer pertinent and the original name can be restored. 147 | 148 | ** The ~completing-read-multiple~ indicator has been removed 149 | :PROPERTIES: 150 | :CUSTOM_ID: h:03b4eae8-fda2-42d4-aaf7-ad87e5211725 151 | :END: 152 | 153 | Previous versions of MCT would prepend a =[CRM]= tag to the minibuffer 154 | prompt of commands powered by ~completing-read-multiple~. While this 155 | is a nice usability enhancement, it is not specific to MCT and thus 156 | should not be part of =mct.el=. Use this in your init file instead: 157 | 158 | #+begin_src emacs-lisp 159 | ;; Add prompt indicator to `completing-read-multiple'. We display 160 | ;; [`completing-read-multiple': ], e.g., 161 | ;; [`completing-read-multiple': ,] if the separator is a comma. This 162 | ;; is adapted from the README of the `vertico' package by Daniel 163 | ;; Mendler. I made some small tweaks to propertize the segments of 164 | ;; the prompt. 165 | (defun crm-indicator (args) 166 | (cons (format "[`crm-separator': %s] %s" 167 | (propertize 168 | (replace-regexp-in-string 169 | "\\`\\[.*?]\\*\\|\\[.*?]\\*\\'" "" 170 | crm-separator) 171 | 'face 'error) 172 | (car args)) 173 | (cdr args))) 174 | 175 | (advice-add #'completing-read-multiple :filter-args #'crm-indicator) 176 | #+end_src 177 | 178 | ** No more IDO-like file navigation 179 | :PROPERTIES: 180 | :CUSTOM_ID: h:4cf5c77c-d991-4a7a-b59c-06f1cf67317b 181 | :END: 182 | 183 | Older versions of MCT had a command for file navigation that would 184 | delete the whole directory component before point, effectively going 185 | back up one directory. While the functionality can be useful, it is not 186 | integral to the MCT experience and thus should not belong in =mct.el=. 187 | Add this to your own configuration file instead: 188 | 189 | #+begin_src emacs-lisp 190 | ;; Adaptation of `icomplete-fido-backward-updir'. 191 | (defun my-backward-updir () 192 | "Delete char before point or go up a directory." 193 | (interactive nil mct-mode) 194 | (cond 195 | ((and (eq (char-before) ?/) 196 | (eq (mct--completion-category) 'file)) 197 | (when (string-equal (minibuffer-contents) "~/") 198 | (delete-minibuffer-contents) 199 | (insert (expand-file-name "~/")) 200 | (goto-char (line-end-position))) 201 | (save-excursion 202 | (goto-char (1- (point))) 203 | (when (search-backward "/" (minibuffer-prompt-end) t) 204 | (delete-region (1+ (point)) (point-max))))) 205 | (t (call-interactively 'backward-delete-char)))) 206 | 207 | (define-key minibuffer-local-filename-completion-map (kbd "DEL") #'my-backward-updir) 208 | #+end_src 209 | 210 | ** Lots of changes under the hood 211 | :PROPERTIES: 212 | :CUSTOM_ID: h:ab0091bf-cbd1-4453-a674-66c195a95622 213 | :END: 214 | 215 | I do not intend to refashion MCT. It works the way it was originally 216 | intended to. What I did is to streamline the code for compatibility 217 | with Emacs 29 and tweak the custom commands to preserve the desired 218 | cyclic behaviour between the minibuffer and the =*Completions*=. 219 | 220 | Experiments such as integration with the ~avy~ package or the ability 221 | to type-to-complete in the =*Completions*= buffer are abandoned. 222 | 223 | Do not expect radical changes henceforth. I shall monitor and/or 224 | contribute to developments in core Emacs and am happy to forever 225 | archive MCT if/when the default completion UI gains the capabilities 226 | that, I think, make the user experience a little bit easier. 227 | 228 | * Version 0.5.0 on 2022-02-08 229 | :PROPERTIES: 230 | :CUSTOM_ID: h:c8d8ad3a-06c9-445d-a4e7-11a68ee17df1 231 | :END: 232 | 233 | This entry covers the changes made to the "Minibuffer and Completions in 234 | Tandem" (=mct= package) since the release of [[#h:1f8fc960-4e4b-4bb1-a1c4-5083f287a28c][version 0.4.0 on 2022-01-19]]. 235 | There have been about 60 commits in the meantime. 236 | 237 | For further details on the user-facing options covered herein, please 238 | read the manual: . Or evaluate the 239 | following expression if you already have =mct= installed: 240 | 241 | #+begin_src emacs-lisp 242 | (info "(mct) Top") 243 | #+end_src 244 | 245 | ** Customisation options 246 | :PROPERTIES: 247 | :CUSTOM_ID: h:95aca1ab-ce8a-4187-94ee-430d44a321b1 248 | :END: 249 | 250 | *** Size of the Completions buffer 251 | :PROPERTIES: 252 | :CUSTOM_ID: h:1b49d3f4-be28-4c6e-a1cb-a473eb87f611 253 | :END: 254 | 255 | The user option ~mct-completion-window-size~ controls the maximum and 256 | minimum height of the window where the =*Completions*= buffer is shown. 257 | It accepts a cons cell in the form of =(MAX-HEIGHT . MIN-HEIGHT)=. Valid 258 | values are natural numbers (positive integers) or functions which return 259 | such numbers. The default is a combination of the two for the sake of 260 | illustration: 261 | 262 | #+begin_src emacs-lisp 263 | (setq mct-completion-window-size (cons #'mct--frame-height-fraction 1)) 264 | #+end_src 265 | 266 | With this in place, mct will let the =*Completions*= grow up to 1/3 of the 267 | frame's height (per the ~mct--frame-height-fraction~). When live 268 | completion is performed (see the user option ~mct-live-completion~), the 269 | window will shrink to fit the candidates. 270 | 271 | To make the =*Completions*= have a fixed height instead, simply set the 272 | same number/function twice. 273 | 274 | If set to nil, mct will simply not try to fit the Completions' buffer to 275 | its window. 276 | 277 | Thanks to Daniel Mendler for the feedback in issue 14: 278 | . 279 | 280 | *** Passlist and blocklist accept completion categories 281 | :PROPERTIES: 282 | :CUSTOM_ID: h:cc1102ca-0a3f-4b34-84e0-c5d684a4c37e 283 | :END: 284 | 285 | The user options ~mct-completion-passlist~ and ~mct-completion-blocklist~ 286 | used to only match symbols of commands like ~find-file~, whereas now they 287 | can affect any completion category such as ~file~, ~kill-ring~, et cetera. 288 | 289 | Sample code: 290 | 291 | #+begin_src emacs-lisp 292 | ;; This is for commands or completion categories that should always pop 293 | ;; up the completions' buffer. It circumvents the default method of 294 | ;; waiting for some user input (see `mct-minimum-input') before 295 | ;; displaying and updating the completions' buffer. 296 | (setq mct-completion-passlist 297 | '(;; Some commands 298 | Info-goto-node 299 | Info-index 300 | Info-menu 301 | vc-retrieve-tag 302 | ;; Some completion categories 303 | imenu 304 | file 305 | buffer 306 | kill-ring 307 | consult-location)) 308 | #+end_src 309 | 310 | The manual provides a comprehensive list of known completion categories: 311 | . 312 | 313 | Or evaluate: 314 | 315 | : (info "(mct) Known completion categories") 316 | 317 | *** Persist live completion for dynamic completion tables 318 | :PROPERTIES: 319 | :CUSTOM_ID: h:21788d38-c916-4a36-93fd-6695776d954f 320 | :END: 321 | 322 | Quoting from the documentation of the ~mct-persist-dynamic-completion~ 323 | user option: 324 | 325 | #+begin_quote 326 | When non-nil, keep dynamic completion live. 327 | 328 | Without any intervention from MCT, the default Emacs behavior for 329 | commands such as ~find-file~ or for a ~file~ completion category is to hide 330 | the =*Completions*= buffer after updating the list of candidates in a 331 | non-exiting fashion (e.g. select a directory and expect to continue 332 | typing the path). This, however, runs contrary to the interaction model 333 | of MCT when it performs live completions, because the user expects the 334 | Completions' buffer to remain visible while typing out the path to the 335 | file. 336 | 337 | When this user option is non-nil (the default) it makes all non-exiting 338 | commands keep the =*Completions*= visible when updating the list of 339 | candidates. 340 | 341 | This applies to prompts in the ~file~ completion category whenever the 342 | user selects a candidate with ~mct-choose-completion-no-exit~, 343 | ~mct-edit-completion~, ~minibuffer-complete~, ~minibuffer-force-complete~ 344 | (i.e. any command that does not exit the minibuffer). 345 | 346 | The two exceptions are (i) when the current completion session runs a 347 | command or category that is blocked by the ~mct-completion-blocklist~ or 348 | (ii) the user option ~mct-live-completion~ is nil. 349 | 350 | The underlying rationale: 351 | 352 | Most completion commands present a flat list of candidates to choose 353 | from. Picking a candidate concludes the session. Some prompts, 354 | however, can recalculate the list of completions based on the selected 355 | candidate. A case in point is ~find-file~ (or any command with the ~file~ 356 | completion category) which dynamically adjusts the completions to show 357 | only the elements which extend the given file system path. We call such 358 | cases "dynamic completion". Due to their particular nature, these need 359 | to be handled explicitly. The present user option is provided primarily 360 | to raise awareness about this state of affairs. 361 | #+end_quote 362 | 363 | *** Deprecation of mct-region-completions-format 364 | :PROPERTIES: 365 | :CUSTOM_ID: h:3f04e53d-c0bf-481e-861d-46511ef37265 366 | :END: 367 | 368 | The ~mct-region-completions-format~ used to be the only user option that 369 | affected the ~mct-region-mode~. It was removed in the interest of 370 | simplicity and to avoid potential complications or bugs. Having 371 | separate user options for ~mct-minibuffer-mode~ and ~mct-region-mode~ would 372 | inevitably lead to duplication and a considerable expansion of the code 373 | base with all sorts of exceptions and checks. 374 | 375 | In-buffer completion now uses the same ~mct-completions-format~ as its 376 | minibuffer-based counterpart. 377 | 378 | *** Deprecation of regexp for name of Completions 379 | :PROPERTIES: 380 | :CUSTOM_ID: h:e40c90cc-3d65-4623-80fc-160df5cb540b 381 | :END: 382 | 383 | There used to be a user option ~mct-completion-windows-regexp~ which 384 | targeted the name of the =*Completions*= buffer. This was legacy code 385 | from the early days of the code base: there is no reason to provide a 386 | customisation of this sort. The ~defcustom~ has been converted into a 387 | ~defvar~ so anyone who still needs the feature can access it: 388 | ~mct--completions-window-name~. 389 | 390 | ** Sorting the completions on Emacs 29 391 | :PROPERTIES: 392 | :CUSTOM_ID: h:4e7f9589-a5c0-426a-98ae-6e4c3ade6531 393 | :END: 394 | 395 | Starting with commit =a46421446f= to emacs.git (by me) users have the 396 | option to control how the completions are sorted: the variable is 397 | ~completions-sort~. Its default value is the same as before, namely, a 398 | lexicographic order, though it accepts an arbitrary function. 399 | 400 | The mct manual provides samples of such functions (improvements are 401 | always welcome): 402 | . 403 | 404 | Or evaluate: 405 | 406 | : (info "(mct) Sort completion candidates on Emacs 29") 407 | 408 | For your convenience: 409 | 410 | #+begin_src emacs-lisp 411 | ;; Some sorting functions... 412 | (defun my-sort-by-alpha-length (elems) 413 | "Sort ELEMS first alphabetically, then by length." 414 | (sort elems (lambda (c1 c2) 415 | (or (string-version-lessp c1 c2) 416 | (< (length c1) (length c2))))))) 417 | 418 | (defun my-sort-by-history (elems) 419 | "Sort ELEMS by minibuffer history. 420 | Use `mct-sort-sort-by-alpha-length' if no history is available." 421 | (if-let ((hist (and (not (eq minibuffer-history-variable t)) 422 | (symbol-value minibuffer-history-variable)))) 423 | (minibuffer--sort-by-position hist elems) 424 | (my-sort-by-alpha-length elems))) 425 | 426 | (defun my-sort-multi-category (elems) 427 | "Sort ELEMS per completion category." 428 | (pcase (mct--completion-category) 429 | ('nil elems) ; no sorting 430 | ('kill-ring elems) 431 | ('project-file (my-sort-by-alpha-length elems)) 432 | (_ (my-sort-by-history elems)))) 433 | 434 | ;; Specify the sorting function. 435 | (setq completions-sort #'my-sort-multi-category) 436 | #+end_src 437 | 438 | Remember to check the manual for all known completion categories. 439 | 440 | ** Changes to the manual 441 | :PROPERTIES: 442 | :CUSTOM_ID: h:e0a18893-eaa7-4805-baa4-b238ac80f2ad 443 | :END: 444 | 445 | + The documentation has been overhauled to better present its 446 | contents. User options now have a parent section while each of them 447 | occupies its own node, making it easier to find exactly what one 448 | needs. 449 | 450 | + There is a workaround on how to circumvent the known issue where 451 | ~global-hl-line-mode~ overrides the mct highlight. Thanks to Tomasz 452 | Hołubowicz for the feedback in issue 1 over at the GitHub mirror: 453 | . 454 | 455 | + A node is included which explains that mct uses the remap mechanism 456 | for specifying key bindings when it is appropriate. As this can lead 457 | to unexpected issues in certain user configurations, the manual 458 | explains how to resolve any conflict. Thanks to Daniel Mendler for 459 | the feedback on the matter (done in various threads). 460 | 461 | + Users of both =mct= and =corfu= packages may experience a conflict. 462 | Daniel Mendler (Corfu's developer) provided a snippet which is covered 463 | in the Corfu's README as well as the mct manual on how to address the 464 | potential issue: . 465 | 466 | + The =emacs-mct= package for Guix is now covered in the section about 467 | installing mct. Thanks to Andrew Tropin and Nicolas Goaziou for 468 | making it happen: . 469 | 470 | ** Bug fixes and other refinements 471 | :PROPERTIES: 472 | :CUSTOM_ID: h:688a7b6e-683c-4687-b6b7-2f7227eee1fb 473 | :END: 474 | 475 | + The timer which controls when the Completions' buffer is displayed or 476 | updated now cancels any outdated constructs instead of creating new 477 | ones. In other words, it is optimised. Thanks to Daniel Mendler for 478 | the patch which was sent via email and is recorded as commit =4ce1004=. 479 | 480 | + Version =0.4.1= fixed a regression with an out-of-bounds motion when 481 | performing certain motions in the =*Completions*= with a numeric 482 | argument. 483 | 484 | + Version =0.4.2= addressed a regression where ~mct-region-mode~ would fail 485 | to perform live updates. Thanks to Z.Du for reporting the bug in 486 | issue 17: . 487 | 488 | + Motions in the Completions buffer are now always based on the 489 | candidate rather than the line. The old design would fail to identify 490 | the first (topmost) candidate if its text was prefixed by entries that 491 | were not part of the completion table, such as icons provided by the 492 | =all-the-icons-completion= package. 493 | 494 | + The command ~mct-keyboard-quit-dwim~ (bound to =C-g= by default) now works 495 | properly with the ~mct-region-mode~. Thanks to James Norman Vladimir 496 | Cash for the contribution in merge request 5: 497 | . 498 | 499 | + The ~mct-highlight-candidate~ no longer hardcodes colour values and 500 | instead inherits from the ~highlight~ face. This makes things easier 501 | for themes (if you use the =modus-themes= package (by me), mct is now 502 | affected by the option =modus-themes-completions=). Thanks to Tomasz 503 | Hołubowicz for the side note about this face in issue 1 over at the 504 | GitHub mirror: . 505 | 506 | + Cycling the completion candidates no longer fails when the one at 507 | point consists of empty spaces and/or newlines. Thanks to Tomasz 508 | Hołubowicz for reporting the bug in issue 2 over at the GitHub mirror: 509 | . 510 | 511 | * Version 0.4.0 on 2022-01-19 512 | :PROPERTIES: 513 | :CUSTOM_ID: h:1f8fc960-4e4b-4bb1-a1c4-5083f287a28c 514 | :END: 515 | 516 | This entry outlines the changes to the "Minibuffer and Completions in 517 | Tandem" (=mct= package) since the release of [[#h:902574cf-edf0-4182-9d34-5e8e28730193][version 0.3.0 on 2021-11-19]]. 518 | There have been more than 120 commits in the meantime. 519 | 520 | For further details, please consult the manual online: 521 | . Or evaluate the following 522 | expression if you already have =mct= installed: 523 | 524 | #+begin_src emacs-lisp 525 | (info "(mct) Top") 526 | #+end_src 527 | 528 | As most changes pertain to optimisations in the code base, we limit this 529 | log to what is of interest to the end-user. 530 | 531 | ** Minibuffer Confines Transcended (aka mct-region-mode) 532 | :PROPERTIES: 533 | :CUSTOM_ID: h:6ee71a37-cada-43af-93b3-a1d65e2be4a8 534 | :END: 535 | 536 | Emacs distinguishes between two types of completion: one that involves 537 | the minibuffer and another for text expansion inside regular buffers. 538 | MCT has supported the former case since its inception, as hinted by its 539 | original name ("Minibuffer and Completions in Tandem"), but would not 540 | work as intended for in-buffer completion. 541 | 542 | This changes with the introduction of a new global minor mode: 543 | ~mct-region-mode~. What once was ~mct-mode~ is now defined as 544 | ~mct-minibuffer-mode~ to better denote the scope of the given 545 | functionality. 546 | 547 | With ~mct-region-mode~ enabled, users get a simplified subset of the 548 | familiar MCT functionality when typing =TAB= or =C-M-i= to complete the 549 | text-at-point in any major-mode that supports 550 | ~completion-at-point-functions~ (e.g. programming modes or Org). 551 | 552 | ~mct-region-mode~ is considered experimental and unstable. Users are 553 | encouraged to report any bugs as well as recommend ways to improve its 554 | functionality or interaction model. The manual has been updated to 555 | cover all the relevant details. 556 | 557 | Daniel Mendler, who is the developer of the =vertico= and =corfu= packages 558 | (alternatives to ~mct-minibuffer-mode~ and ~mct-region-mode~, respectively), 559 | was intstrumental in making ~mct-region-mode~ happen. Daniel's patches 560 | helped with everything from (i) the proper functioning of 561 | ~mct-region-mode~, (ii) the separation between ~mct-minibuffer-mode~ and 562 | ~mct-region-mode~, (iii) the overall setup of the minor modes, and (iv) 563 | lots of other crucial details of the overall design of MCT. In short: 564 | there would be no ~mct-region-mode~ without Daniel's contributions. Any 565 | remaining errors or omissions are my own. 566 | 567 | Given this new functionality, we can now joke that "MCT" stands for 568 | "Minibuffer Confines Transcended". 569 | 570 | * Version 0.3.0 on 2021-11-19 571 | :PROPERTIES: 572 | :CUSTOM_ID: h:902574cf-edf0-4182-9d34-5e8e28730193 573 | :END: 574 | 575 | This entry describes the changes to Minibuffer and Completions in Tandem 576 | (mct) since the release of [[#h:4fab7648-d672-4af3-90b5-74242292f633][version 0.2.0 on 2021-11-12]]. There have been 577 | more than 40 commits since then. For further details, please consult 578 | the manual online: . Or evaluate 579 | the following expression if you have the =mct= package installed: 580 | 581 | #+begin_src emacs-lisp 582 | (info "(mct) Top") 583 | #+end_src 584 | 585 | As this release is a continuation of version =0.2.0=, the changelog for 586 | that version is also provided below (I released version =0.2.0= earlier 587 | than anticipated so that users could get a stable package on GNU ELPA). 588 | Here is a brief description of what has been achieved in =0.3.0=. 589 | 590 | ** MCT on Emacs 27 591 | :PROPERTIES: 592 | :CUSTOM_ID: h:c05100f7-a525-4d76-8f88-8de4cfe69e67 593 | :END: 594 | 595 | + MCT now works on Emacs 27. This was not possible in the past because 596 | ~mct-mode~ was originally designed to operate with the =one-column= style 597 | of the ~completions-format~, which was added in Emacs 28. To make 598 | everything behave intuitively, several parts had to be abstracted and 599 | refactored (the changelog of version =0.2.0= (further below) covers 600 | everything not mentioned here). 601 | 602 | + The scenaria where the functionality was thoroughly tested involve all 603 | the available formats and cover commands that fulfil the following 604 | criteria: 605 | 606 | - Plain completion candidates, as in ~switch-to-buffer~. 607 | - Dynamic completion like that of ~find-file~. 608 | - Annotated candidates, as seen in ~describe-symbol~ for versions of 609 | Emacs 28 or higher. 610 | - Commands where candidates are grouped by heading, as done by various 611 | extensions of the =consult= package, such as ~consult-imenu~. 612 | - Commands where no completion category is associated with them. 613 | 614 | + The only change which is visible to the user is the implementation 615 | of a bespoke overlay to highlight the current candidate. In 616 | previous versions, this was provided by the built-in ~hl-line-mode~, 617 | though that does not work as intended with either the =vertical= or 618 | =horizontal= layouts of the ~completions-format~ as it covers the whole 619 | line instead of the candidate at point. 620 | 621 | + The highlight extends to the edge of the window when the =one-column= 622 | format is used for the ~completions-format~ (Emacs 28 or higher). In 623 | the other views it stretches from the beginning to the end of the 624 | completion candidate. 625 | 626 | + Thanks to Case Duckworth for the initial request and subsequent 627 | testing in issue 1: . 628 | 629 | ** Miscellaneous changes 630 | :PROPERTIES: 631 | :CUSTOM_ID: h:db448e8b-5416-4561-993a-4f5f3a8ad7e4 632 | :END: 633 | 634 | + There is a new command that is active in the minibuffer which allows 635 | to complete and exit immediately: =C-RET= (~mct-complete-and-exit~). This 636 | economises on key presses when all the user wants is to select the 637 | top-most candidate (or last highlighted one) without first switching 638 | to the Completions' buffer and then confirming it from there (=RET= in 639 | the =*Completions*= buffer completes and exits directly). 640 | 641 | - Thanks to José Antonio Ortega Ruiz for the contribution in merge 642 | requests 3 and 4 as discussed in issue 8: 643 | 644 | + 645 | + 646 | + 647 | 648 | - Note that "exit" in this context denotes the process of terminating 649 | the session while accepting the current input. The term used to 650 | quit without accepting the input is "abort". 651 | 652 | + The ~mct-mode~ does not get activated in contexts where (i) the 653 | minibuffer is involved but (ii) no completion takes place. For 654 | example, the ~eval-expression~ command (bound to =M-:= by default). 655 | 656 | + ~mct-mode~ no longer remaps the faces of the ~display-line-numbers-mode~. 657 | This was a useful experiment from the early days of the code base, 658 | although it is bad practice for a user-facing package. 659 | 660 | + Various tweaks and refinements to the manual. 661 | 662 | + Retroactive introduction of a CHANGELOG.org file and coverage of all 663 | noteworthy changes hitherto. 664 | 665 | * Version 0.2.0 on 2021-11-12 666 | :PROPERTIES: 667 | :CUSTOM_ID: h:4fab7648-d672-4af3-90b5-74242292f633 668 | :END: 669 | 670 | This entry describes the changes to Minibuffer and Completions in Tandem 671 | (mct) since the release of [[#h:a4b2152a-96e2-46fc-b9e0-ba223028118f][version 0.1.0 on 2021-10-22]]. There have been 672 | 70 commits since then. For further details, please consult the manual 673 | online: . Or evaluate the following 674 | expression if you have the =mct= package installed: 675 | 676 | #+begin_src emacs-lisp 677 | (info "(mct) Top") 678 | #+end_src 679 | 680 | ** Packaged version of MCT 681 | :PROPERTIES: 682 | :CUSTOM_ID: h:0fb1fb23-636f-41f3-97bf-880d83ac42e0 683 | :END: 684 | 685 | =mct= is now available on the official GNU ELPA archive for users of Emacs 686 | version 28 or higher. One can install the package without any further 687 | configuration. The following commands shall suffice: 688 | 689 | #+begin_src 690 | M-x package-refresh-contents 691 | M-x package-install RET mct 692 | #+end_src 693 | 694 | ** Changes to the format and placement of the Completions 695 | :PROPERTIES: 696 | :CUSTOM_ID: h:97eba994-45ad-4f86-945f-a60772f764b5 697 | :END: 698 | 699 | + The user option ~mct-live-completion~ controls how and when the 700 | Completions' buffer should be placed in a window and be updated live 701 | in response to user feedback. Copying from the doc string: 702 | 703 | #+begin_quote 704 | mct-live-completion is a variable defined in ‘mct.el’. 705 | 706 | Its value is t 707 | 708 | Control auto-display and live-update of Completions' buffer. 709 | 710 | When nil, the user has to manually request completions, using the 711 | regular activating commands. The Completions' buffer is never updated 712 | live to match user input. Updating has to be handled manually. This 713 | is like the out-of-the-box minibuffer completion experience. 714 | 715 | When set to the value =visible=, the Completions' buffer is live 716 | updated only if it is visible. The actual display of the completions 717 | is still handled manually. For this reason, the =visible= style does 718 | not read the =mct-minimum-input=, meaning that it will always try to 719 | live update the visible completions, regardless of input length. 720 | 721 | When non-nil (the default), the Completions' buffer is automatically 722 | displayed once the =mct-minimum-input= is met and is hidden if the 723 | input drops below that threshold. While visible, the buffer is 724 | updated live to match the user input. 725 | 726 | Note that every function in the =mct-completion-passlist= ignores this 727 | option altogether. This means that every such command will always 728 | show the Completions' buffer automatically and will always update its 729 | contents live. Same principle for every function declared in the 730 | =mct-completion-blocklist=, which will always disable both the 731 | automatic display and live updating of the Completions' buffer. 732 | #+end_quote 733 | 734 | - Thanks to Jonathan Irving for the feedback in issue 4: 735 | . 736 | 737 | + As with all buffers, the placement of the =*Completions*= can be 738 | controlled with the ~display-buffer~ machinery. The default is to show 739 | the completions at the bottom of the frame, though users can easily 740 | move it to, say, the left side window. The doc string of the user 741 | option ~mct-display-buffer-action~ explains how to do so. 742 | 743 | - Thanks to Philip Kaludercic for the initial implementation in commit 744 | =436b24e= (was sent via email as a patch). 745 | 746 | - Thanks to Kostadin Ninev for reporting a bug where the Completions' 747 | buffer would proliferate during completion: 748 | . It was fixed by 749 | Philip Kaludercic in commit =51c1e17=. 750 | 751 | + MCT now supports all the available styles of the ~completions-format~, 752 | whereas the original design was only meant to work with the value 753 | =one-column=, which was introduced in Emacs 28. The user option is 754 | ~mct-completions-format~. If that variable is set with ~setq~, the 755 | ~mct-mode~ has to be restarted manually for changes to take effect 756 | (setting the variable through ~customize-set-variable~ (and related) 757 | handles the mode reloading automatically). 758 | 759 | - Thanks to Philip Kaludercic for the patch in commit =b392b0b=. 760 | 761 | - Several changes were then made to ensure that the cyclic motions 762 | that move between the =*Completions*= and the minibuffer work 763 | intuitively in a grid view. In short: =C-n=, =C-p= or the down/up arrow 764 | keys, perform a vertical motion, while the left/right arrow keys 765 | move laterally. Prior to those changes, =C-n= or down arrow as well 766 | as =C-p= or up arrow, would perform a lateral motion as that is 767 | internally the meaning of the next/previous completion candidate. 768 | 769 | - The command ~mct-choose-completion-number~ was updated to throw a user 770 | error when a grid view is active. That is because it is designed to 771 | jump to a given line number, which only works as intended when there 772 | is only one candidate per line. (Perhaps a future release should 773 | overlay characters over candidates in the grid view to select them 774 | directly.) 775 | 776 | + The ~mct-mode~ no longer sets the =completions-detailed= variable. That 777 | is a matter of user preference. It is not integral to the 778 | functionality of MCT. 779 | 780 | ** Group motions 781 | :PROPERTIES: 782 | :CUSTOM_ID: h:5f9027f9-fad0-4c03-8269-60eb670d0b38 783 | :END: 784 | 785 | + Emacs 28 provides infrastructure for commands to group candidates 786 | based on their contents. These groups can have their own heading in 787 | the Completions' buffer, as well as a separator. Overall, it makes 788 | things look more organised. The commands ~mct-next-completion-group~ 789 | and ~mct-previous-completion-group~ move between those headings. While 790 | in the =*Completions*= buffer, they are bound to =M-n= and =M-p=, 791 | respectively. Thanks to James Norman Vladimir Cash for the 792 | contribution in merge request 2: 793 | . 794 | 795 | ** Miscellaneous changes 796 | :PROPERTIES: 797 | :CUSTOM_ID: h:ed67abef-dad3-4620-bc70-1c3dc268db59 798 | :END: 799 | 800 | + The =TAB= key in the Completions' buffer never exits the minibuffer (the 801 | command is ~mct-choose-completion-no-exit~). Instead, it expands the 802 | current candidate in the minibuffer and switches focus to it. Before, 803 | this behaviour would only happen in ~find-file~ and related prompts, but 804 | consistency/predictability is better. 805 | 806 | [ By contrast, =RET= (~mct-choose-completion-exit~) in the Completions 807 | buffer always exits with the candidate at point. ] 808 | 809 | Note that in this context "exit" means to close the session and accept 810 | the current input. 811 | 812 | + There is a new heuristic to deal with commands that ~let~ bind the 813 | ~crm-separator~ (e.g. ~org-set-tags-command~ sets the separator to =:=). 814 | This is used to make =M-RET= (~mct-choose-completion-dwim~) in the 815 | Completions buffer work in all ~completing-read-multiple~ contexts. 816 | Thanks to James Norman Vladimir Cash for contributing the heuristic in 817 | merge request 1: 818 | . 819 | 820 | + The aforementioned =M-RET= command used to have the same effect as =RET= 821 | when not in a ~completing-read-multiple~ prompt ("CRM prompt"). This 822 | has now been revised to behave like =TAB= instead (as described further 823 | above), which is consistent with the ordinary behaviour of =M-RET= in 824 | CRM prompts where it appends the candidate at point to the minibuffer 825 | without exiting. 826 | 827 | + The check for ~display-line-numbers-mode~ tests whether it is bound, 828 | thus avoiding possible errors. Thanks to Philip Kaludercic for the 829 | patch in commit =6bd2457=. 830 | 831 | + Made several improvements to doc strings and various snippets of code. 832 | 833 | ** Updates to the manual 834 | :PROPERTIES: 835 | :CUSTOM_ID: h:19c69838-c480-4b98-80e3-da25642a2c23 836 | :END: 837 | 838 | + All of the aforementioned were documented, where appropriate. 839 | + A Makefile is now on offer, which is used to generate the mct.info and 840 | mct.texi files. Thanks to Philip Kaludercic for the patch in commit 841 | =295bac0=. 842 | + A sample setup is available for =mct= as well as several built-in 843 | options pertaining to the minibuffer. 844 | + There are sections about third-party extensions as well as one that 845 | describes alternatives to MCT. Thanks to Manuel Uberti for the 846 | feedback in issue 5: . 847 | + The "Acknowledgements" section includes the names of people who have 848 | contributed to the project in one way or another (code, ideas, user 849 | feedback, ...). 850 | 851 | * Version 0.1.0 on 2021-10-22 852 | :PROPERTIES: 853 | :CUSTOM_ID: h:a4b2152a-96e2-46fc-b9e0-ba223028118f 854 | :END: 855 | 856 | Initial release. The mct.el file derived from the now-deprecated 857 | prot-minibuffer.el (part of [[https://gitlab.com/protesilaos/dotfiles][my dotfiles]]), which I had been using for 858 | more than six months full time. 859 | -------------------------------------------------------------------------------- /COPYING: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU General Public License is a free, copyleft license for 11 | software and other kinds of works. 12 | 13 | The licenses for most software and other practical works are designed 14 | to take away your freedom to share and change the works. By contrast, 15 | the GNU General Public License is intended to guarantee your freedom to 16 | share and change all versions of a program--to make sure it remains free 17 | software for all its users. We, the Free Software Foundation, use the 18 | GNU General Public License for most of our software; it applies also to 19 | any other work released this way by its authors. You can apply it to 20 | your programs, too. 21 | 22 | When we speak of free software, we are referring to freedom, not 23 | price. Our General Public Licenses are designed to make sure that you 24 | have the freedom to distribute copies of free software (and charge for 25 | them if you wish), that you receive source code or can get it if you 26 | want it, that you can change the software or use pieces of it in new 27 | free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you 30 | these rights or asking you to surrender the rights. Therefore, you have 31 | certain responsibilities if you distribute copies of the software, or if 32 | you modify it: responsibilities to respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether 35 | gratis or for a fee, you must pass on to the recipients the same 36 | freedoms that you received. You must make sure that they, too, receive 37 | or can get the source code. And you must show them these terms so they 38 | know their rights. 39 | 40 | Developers that use the GNU GPL protect your rights with two steps: 41 | (1) assert copyright on the software, and (2) offer you this License 42 | giving you legal permission to copy, distribute and/or modify it. 43 | 44 | For the developers' and authors' protection, the GPL clearly explains 45 | that there is no warranty for this free software. For both users' and 46 | authors' sake, the GPL requires that modified versions be marked as 47 | changed, so that their problems will not be attributed erroneously to 48 | authors of previous versions. 49 | 50 | Some devices are designed to deny users access to install or run 51 | modified versions of the software inside them, although the manufacturer 52 | can do so. This is fundamentally incompatible with the aim of 53 | protecting users' freedom to change the software. The systematic 54 | pattern of such abuse occurs in the area of products for individuals to 55 | use, which is precisely where it is most unacceptable. Therefore, we 56 | have designed this version of the GPL to prohibit the practice for those 57 | products. If such problems arise substantially in other domains, we 58 | stand ready to extend this provision to those domains in future versions 59 | of the GPL, as needed to protect the freedom of users. 60 | 61 | Finally, every program is threatened constantly by software patents. 62 | States should not allow patents to restrict development and use of 63 | software on general-purpose computers, but in those that do, we wish to 64 | avoid the special danger that patents applied to a free program could 65 | make it effectively proprietary. To prevent this, the GPL assures that 66 | patents cannot be used to render the program non-free. 67 | 68 | The precise terms and conditions for copying, distribution and 69 | modification follow. 70 | 71 | TERMS AND CONDITIONS 72 | 73 | 0. Definitions. 74 | 75 | "This License" refers to version 3 of the GNU General Public License. 76 | 77 | "Copyright" also means copyright-like laws that apply to other kinds of 78 | works, such as semiconductor masks. 79 | 80 | "The Program" refers to any copyrightable work licensed under this 81 | License. Each licensee is addressed as "you". "Licensees" and 82 | "recipients" may be individuals or organizations. 83 | 84 | To "modify" a work means to copy from or adapt all or part of the work 85 | in a fashion requiring copyright permission, other than the making of an 86 | exact copy. The resulting work is called a "modified version" of the 87 | earlier work or a work "based on" the earlier work. 88 | 89 | A "covered work" means either the unmodified Program or a work based 90 | on the Program. 91 | 92 | To "propagate" a work means to do anything with it that, without 93 | permission, would make you directly or secondarily liable for 94 | infringement under applicable copyright law, except executing it on a 95 | computer or modifying a private copy. Propagation includes copying, 96 | distribution (with or without modification), making available to the 97 | public, and in some countries other activities as well. 98 | 99 | To "convey" a work means any kind of propagation that enables other 100 | parties to make or receive copies. Mere interaction with a user through 101 | a computer network, with no transfer of a copy, is not conveying. 102 | 103 | An interactive user interface displays "Appropriate Legal Notices" 104 | to the extent that it includes a convenient and prominently visible 105 | feature that (1) displays an appropriate copyright notice, and (2) 106 | tells the user that there is no warranty for the work (except to the 107 | extent that warranties are provided), that licensees may convey the 108 | work under this License, and how to view a copy of this License. If 109 | the interface presents a list of user commands or options, such as a 110 | menu, a prominent item in the list meets this criterion. 111 | 112 | 1. Source Code. 113 | 114 | The "source code" for a work means the preferred form of the work 115 | for making modifications to it. "Object code" means any non-source 116 | form of a work. 117 | 118 | A "Standard Interface" means an interface that either is an official 119 | standard defined by a recognized standards body, or, in the case of 120 | interfaces specified for a particular programming language, one that 121 | is widely used among developers working in that language. 122 | 123 | The "System Libraries" of an executable work include anything, other 124 | than the work as a whole, that (a) is included in the normal form of 125 | packaging a Major Component, but which is not part of that Major 126 | Component, and (b) serves only to enable use of the work with that 127 | Major Component, or to implement a Standard Interface for which an 128 | implementation is available to the public in source code form. A 129 | "Major Component", in this context, means a major essential component 130 | (kernel, window system, and so on) of the specific operating system 131 | (if any) on which the executable work runs, or a compiler used to 132 | produce the work, or an object code interpreter used to run it. 133 | 134 | The "Corresponding Source" for a work in object code form means all 135 | the source code needed to generate, install, and (for an executable 136 | work) run the object code and to modify the work, including scripts to 137 | control those activities. However, it does not include the work's 138 | System Libraries, or general-purpose tools or generally available free 139 | programs which are used unmodified in performing those activities but 140 | which are not part of the work. For example, Corresponding Source 141 | includes interface definition files associated with source files for 142 | the work, and the source code for shared libraries and dynamically 143 | linked subprograms that the work is specifically designed to require, 144 | such as by intimate data communication or control flow between those 145 | subprograms and other parts of the work. 146 | 147 | The Corresponding Source need not include anything that users 148 | can regenerate automatically from other parts of the Corresponding 149 | Source. 150 | 151 | The Corresponding Source for a work in source code form is that 152 | same work. 153 | 154 | 2. Basic Permissions. 155 | 156 | All rights granted under this License are granted for the term of 157 | copyright on the Program, and are irrevocable provided the stated 158 | conditions are met. This License explicitly affirms your unlimited 159 | permission to run the unmodified Program. The output from running a 160 | covered work is covered by this License only if the output, given its 161 | content, constitutes a covered work. This License acknowledges your 162 | rights of fair use or other equivalent, as provided by copyright law. 163 | 164 | You may make, run and propagate covered works that you do not 165 | convey, without conditions so long as your license otherwise remains 166 | in force. You may convey covered works to others for the sole purpose 167 | of having them make modifications exclusively for you, or provide you 168 | with facilities for running those works, provided that you comply with 169 | the terms of this License in conveying all material for which you do 170 | not control copyright. Those thus making or running the covered works 171 | for you must do so exclusively on your behalf, under your direction 172 | and control, on terms that prohibit them from making any copies of 173 | your copyrighted material outside their relationship with you. 174 | 175 | Conveying under any other circumstances is permitted solely under 176 | the conditions stated below. Sublicensing is not allowed; section 10 177 | makes it unnecessary. 178 | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 180 | 181 | No covered work shall be deemed part of an effective technological 182 | measure under any applicable law fulfilling obligations under article 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 184 | similar laws prohibiting or restricting circumvention of such 185 | measures. 186 | 187 | When you convey a covered work, you waive any legal power to forbid 188 | circumvention of technological measures to the extent such circumvention 189 | is effected by exercising rights under this License with respect to 190 | the covered work, and you disclaim any intention to limit operation or 191 | modification of the work as a means of enforcing, against the work's 192 | users, your or third parties' legal rights to forbid circumvention of 193 | technological measures. 194 | 195 | 4. Conveying Verbatim Copies. 196 | 197 | You may convey verbatim copies of the Program's source code as you 198 | receive it, in any medium, provided that you conspicuously and 199 | appropriately publish on each copy an appropriate copyright notice; 200 | keep intact all notices stating that this License and any 201 | non-permissive terms added in accord with section 7 apply to the code; 202 | keep intact all notices of the absence of any warranty; and give all 203 | recipients a copy of this License along with the Program. 204 | 205 | You may charge any price or no price for each copy that you convey, 206 | and you may offer support or warranty protection for a fee. 207 | 208 | 5. Conveying Modified Source Versions. 209 | 210 | You may convey a work based on the Program, or the modifications to 211 | produce it from the Program, in the form of source code under the 212 | terms of section 4, provided that you also meet all of these conditions: 213 | 214 | a) The work must carry prominent notices stating that you modified 215 | it, and giving a relevant date. 216 | 217 | b) The work must carry prominent notices stating that it is 218 | released under this License and any conditions added under section 219 | 7. This requirement modifies the requirement in section 4 to 220 | "keep intact all notices". 221 | 222 | c) You must license the entire work, as a whole, under this 223 | License to anyone who comes into possession of a copy. This 224 | License will therefore apply, along with any applicable section 7 225 | additional terms, to the whole of the work, and all its parts, 226 | regardless of how they are packaged. This License gives no 227 | permission to license the work in any other way, but it does not 228 | invalidate such permission if you have separately received it. 229 | 230 | d) If the work has interactive user interfaces, each must display 231 | Appropriate Legal Notices; however, if the Program has interactive 232 | interfaces that do not display Appropriate Legal Notices, your 233 | work need not make them do so. 234 | 235 | A compilation of a covered work with other separate and independent 236 | works, which are not by their nature extensions of the covered work, 237 | and which are not combined with it such as to form a larger program, 238 | in or on a volume of a storage or distribution medium, is called an 239 | "aggregate" if the compilation and its resulting copyright are not 240 | used to limit the access or legal rights of the compilation's users 241 | beyond what the individual works permit. Inclusion of a covered work 242 | in an aggregate does not cause this License to apply to the other 243 | parts of the aggregate. 244 | 245 | 6. Conveying Non-Source Forms. 246 | 247 | You may convey a covered work in object code form under the terms 248 | of sections 4 and 5, provided that you also convey the 249 | machine-readable Corresponding Source under the terms of this License, 250 | in one of these ways: 251 | 252 | a) Convey the object code in, or embodied in, a physical product 253 | (including a physical distribution medium), accompanied by the 254 | Corresponding Source fixed on a durable physical medium 255 | customarily used for software interchange. 256 | 257 | b) Convey the object code in, or embodied in, a physical product 258 | (including a physical distribution medium), accompanied by a 259 | written offer, valid for at least three years and valid for as 260 | long as you offer spare parts or customer support for that product 261 | model, to give anyone who possesses the object code either (1) a 262 | copy of the Corresponding Source for all the software in the 263 | product that is covered by this License, on a durable physical 264 | medium customarily used for software interchange, for a price no 265 | more than your reasonable cost of physically performing this 266 | conveying of source, or (2) access to copy the 267 | Corresponding Source from a network server at no charge. 268 | 269 | c) Convey individual copies of the object code with a copy of the 270 | written offer to provide the Corresponding Source. This 271 | alternative is allowed only occasionally and noncommercially, and 272 | only if you received the object code with such an offer, in accord 273 | with subsection 6b. 274 | 275 | d) Convey the object code by offering access from a designated 276 | place (gratis or for a charge), and offer equivalent access to the 277 | Corresponding Source in the same way through the same place at no 278 | further charge. You need not require recipients to copy the 279 | Corresponding Source along with the object code. If the place to 280 | copy the object code is a network server, the Corresponding Source 281 | may be on a different server (operated by you or a third party) 282 | that supports equivalent copying facilities, provided you maintain 283 | clear directions next to the object code saying where to find the 284 | Corresponding Source. Regardless of what server hosts the 285 | Corresponding Source, you remain obligated to ensure that it is 286 | available for as long as needed to satisfy these requirements. 287 | 288 | e) Convey the object code using peer-to-peer transmission, provided 289 | you inform other peers where the object code and Corresponding 290 | Source of the work are being offered to the general public at no 291 | charge under subsection 6d. 292 | 293 | A separable portion of the object code, whose source code is excluded 294 | from the Corresponding Source as a System Library, need not be 295 | included in conveying the object code work. 296 | 297 | A "User Product" is either (1) a "consumer product", which means any 298 | tangible personal property which is normally used for personal, family, 299 | or household purposes, or (2) anything designed or sold for incorporation 300 | into a dwelling. In determining whether a product is a consumer product, 301 | doubtful cases shall be resolved in favor of coverage. For a particular 302 | product received by a particular user, "normally used" refers to a 303 | typical or common use of that class of product, regardless of the status 304 | of the particular user or of the way in which the particular user 305 | actually uses, or expects or is expected to use, the product. A product 306 | is a consumer product regardless of whether the product has substantial 307 | commercial, industrial or non-consumer uses, unless such uses represent 308 | the only significant mode of use of the product. 309 | 310 | "Installation Information" for a User Product means any methods, 311 | procedures, authorization keys, or other information required to install 312 | and execute modified versions of a covered work in that User Product from 313 | a modified version of its Corresponding Source. The information must 314 | suffice to ensure that the continued functioning of the modified object 315 | code is in no case prevented or interfered with solely because 316 | modification has been made. 317 | 318 | If you convey an object code work under this section in, or with, or 319 | specifically for use in, a User Product, and the conveying occurs as 320 | part of a transaction in which the right of possession and use of the 321 | User Product is transferred to the recipient in perpetuity or for a 322 | fixed term (regardless of how the transaction is characterized), the 323 | Corresponding Source conveyed under this section must be accompanied 324 | by the Installation Information. But this requirement does not apply 325 | if neither you nor any third party retains the ability to install 326 | modified object code on the User Product (for example, the work has 327 | been installed in ROM). 328 | 329 | The requirement to provide Installation Information does not include a 330 | requirement to continue to provide support service, warranty, or updates 331 | for a work that has been modified or installed by the recipient, or for 332 | the User Product in which it has been modified or installed. Access to a 333 | network may be denied when the modification itself materially and 334 | adversely affects the operation of the network or violates the rules and 335 | protocols for communication across the network. 336 | 337 | Corresponding Source conveyed, and Installation Information provided, 338 | in accord with this section must be in a format that is publicly 339 | documented (and with an implementation available to the public in 340 | source code form), and must require no special password or key for 341 | unpacking, reading or copying. 342 | 343 | 7. Additional Terms. 344 | 345 | "Additional permissions" are terms that supplement the terms of this 346 | License by making exceptions from one or more of its conditions. 347 | Additional permissions that are applicable to the entire Program shall 348 | be treated as though they were included in this License, to the extent 349 | that they are valid under applicable law. If additional permissions 350 | apply only to part of the Program, that part may be used separately 351 | under those permissions, but the entire Program remains governed by 352 | this License without regard to the additional permissions. 353 | 354 | When you convey a copy of a covered work, you may at your option 355 | remove any additional permissions from that copy, or from any part of 356 | it. (Additional permissions may be written to require their own 357 | removal in certain cases when you modify the work.) You may place 358 | additional permissions on material, added by you to a covered work, 359 | for which you have or can give appropriate copyright permission. 360 | 361 | Notwithstanding any other provision of this License, for material you 362 | add to a covered work, you may (if authorized by the copyright holders of 363 | that material) supplement the terms of this License with terms: 364 | 365 | a) Disclaiming warranty or limiting liability differently from the 366 | terms of sections 15 and 16 of this License; or 367 | 368 | b) Requiring preservation of specified reasonable legal notices or 369 | author attributions in that material or in the Appropriate Legal 370 | Notices displayed by works containing it; or 371 | 372 | c) Prohibiting misrepresentation of the origin of that material, or 373 | requiring that modified versions of such material be marked in 374 | reasonable ways as different from the original version; or 375 | 376 | d) Limiting the use for publicity purposes of names of licensors or 377 | authors of the material; or 378 | 379 | e) Declining to grant rights under trademark law for use of some 380 | trade names, trademarks, or service marks; or 381 | 382 | f) Requiring indemnification of licensors and authors of that 383 | material by anyone who conveys the material (or modified versions of 384 | it) with contractual assumptions of liability to the recipient, for 385 | any liability that these contractual assumptions directly impose on 386 | those licensors and authors. 387 | 388 | All other non-permissive additional terms are considered "further 389 | restrictions" within the meaning of section 10. If the Program as you 390 | received it, or any part of it, contains a notice stating that it is 391 | governed by this License along with a term that is a further 392 | restriction, you may remove that term. If a license document contains 393 | a further restriction but permits relicensing or conveying under this 394 | License, you may add to a covered work material governed by the terms 395 | of that license document, provided that the further restriction does 396 | not survive such relicensing or conveying. 397 | 398 | If you add terms to a covered work in accord with this section, you 399 | must place, in the relevant source files, a statement of the 400 | additional terms that apply to those files, or a notice indicating 401 | where to find the applicable terms. 402 | 403 | Additional terms, permissive or non-permissive, may be stated in the 404 | form of a separately written license, or stated as exceptions; 405 | the above requirements apply either way. 406 | 407 | 8. Termination. 408 | 409 | You may not propagate or modify a covered work except as expressly 410 | provided under this License. Any attempt otherwise to propagate or 411 | modify it is void, and will automatically terminate your rights under 412 | this License (including any patent licenses granted under the third 413 | paragraph of section 11). 414 | 415 | However, if you cease all violation of this License, then your 416 | license from a particular copyright holder is reinstated (a) 417 | provisionally, unless and until the copyright holder explicitly and 418 | finally terminates your license, and (b) permanently, if the copyright 419 | holder fails to notify you of the violation by some reasonable means 420 | prior to 60 days after the cessation. 421 | 422 | Moreover, your license from a particular copyright holder is 423 | reinstated permanently if the copyright holder notifies you of the 424 | violation by some reasonable means, this is the first time you have 425 | received notice of violation of this License (for any work) from that 426 | copyright holder, and you cure the violation prior to 30 days after 427 | your receipt of the notice. 428 | 429 | Termination of your rights under this section does not terminate the 430 | licenses of parties who have received copies or rights from you under 431 | this License. If your rights have been terminated and not permanently 432 | reinstated, you do not qualify to receive new licenses for the same 433 | material under section 10. 434 | 435 | 9. Acceptance Not Required for Having Copies. 436 | 437 | You are not required to accept this License in order to receive or 438 | run a copy of the Program. Ancillary propagation of a covered work 439 | occurring solely as a consequence of using peer-to-peer transmission 440 | to receive a copy likewise does not require acceptance. However, 441 | nothing other than this License grants you permission to propagate or 442 | modify any covered work. These actions infringe copyright if you do 443 | not accept this License. Therefore, by modifying or propagating a 444 | covered work, you indicate your acceptance of this License to do so. 445 | 446 | 10. Automatic Licensing of Downstream Recipients. 447 | 448 | Each time you convey a covered work, the recipient automatically 449 | receives a license from the original licensors, to run, modify and 450 | propagate that work, subject to this License. You are not responsible 451 | for enforcing compliance by third parties with this License. 452 | 453 | An "entity transaction" is a transaction transferring control of an 454 | organization, or substantially all assets of one, or subdividing an 455 | organization, or merging organizations. If propagation of a covered 456 | work results from an entity transaction, each party to that 457 | transaction who receives a copy of the work also receives whatever 458 | licenses to the work the party's predecessor in interest had or could 459 | give under the previous paragraph, plus a right to possession of the 460 | Corresponding Source of the work from the predecessor in interest, if 461 | the predecessor has it or can get it with reasonable efforts. 462 | 463 | You may not impose any further restrictions on the exercise of the 464 | rights granted or affirmed under this License. For example, you may 465 | not impose a license fee, royalty, or other charge for exercise of 466 | rights granted under this License, and you may not initiate litigation 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that 468 | any patent claim is infringed by making, using, selling, offering for 469 | sale, or importing the Program or any portion of it. 470 | 471 | 11. Patents. 472 | 473 | A "contributor" is a copyright holder who authorizes use under this 474 | License of the Program or a work on which the Program is based. The 475 | work thus licensed is called the contributor's "contributor version". 476 | 477 | A contributor's "essential patent claims" are all patent claims 478 | owned or controlled by the contributor, whether already acquired or 479 | hereafter acquired, that would be infringed by some manner, permitted 480 | by this License, of making, using, or selling its contributor version, 481 | but do not include claims that would be infringed only as a 482 | consequence of further modification of the contributor version. For 483 | purposes of this definition, "control" includes the right to grant 484 | patent sublicenses in a manner consistent with the requirements of 485 | this License. 486 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free 488 | patent license under the contributor's essential patent claims, to 489 | make, use, sell, offer for sale, import and otherwise run, modify and 490 | propagate the contents of its contributor version. 491 | 492 | In the following three paragraphs, a "patent license" is any express 493 | agreement or commitment, however denominated, not to enforce a patent 494 | (such as an express permission to practice a patent or covenant not to 495 | sue for patent infringement). To "grant" such a patent license to a 496 | party means to make such an agreement or commitment not to enforce a 497 | patent against the party. 498 | 499 | If you convey a covered work, knowingly relying on a patent license, 500 | and the Corresponding Source of the work is not available for anyone 501 | to copy, free of charge and under the terms of this License, through a 502 | publicly available network server or other readily accessible means, 503 | then you must either (1) cause the Corresponding Source to be so 504 | available, or (2) arrange to deprive yourself of the benefit of the 505 | patent license for this particular work, or (3) arrange, in a manner 506 | consistent with the requirements of this License, to extend the patent 507 | license to downstream recipients. "Knowingly relying" means you have 508 | actual knowledge that, but for the patent license, your conveying the 509 | covered work in a country, or your recipient's use of the covered work 510 | in a country, would infringe one or more identifiable patents in that 511 | country that you have reason to believe are valid. 512 | 513 | If, pursuant to or in connection with a single transaction or 514 | arrangement, you convey, or propagate by procuring conveyance of, a 515 | covered work, and grant a patent license to some of the parties 516 | receiving the covered work authorizing them to use, propagate, modify 517 | or convey a specific copy of the covered work, then the patent license 518 | you grant is automatically extended to all recipients of the covered 519 | work and works based on it. 520 | 521 | A patent license is "discriminatory" if it does not include within 522 | the scope of its coverage, prohibits the exercise of, or is 523 | conditioned on the non-exercise of one or more of the rights that are 524 | specifically granted under this License. You may not convey a covered 525 | work if you are a party to an arrangement with a third party that is 526 | in the business of distributing software, under which you make payment 527 | to the third party based on the extent of your activity of conveying 528 | the work, and under which the third party grants, to any of the 529 | parties who would receive the covered work from you, a discriminatory 530 | patent license (a) in connection with copies of the covered work 531 | conveyed by you (or copies made from those copies), or (b) primarily 532 | for and in connection with specific products or compilations that 533 | contain the covered work, unless you entered into that arrangement, 534 | or that patent license was granted, prior to 28 March 2007. 535 | 536 | Nothing in this License shall be construed as excluding or limiting 537 | any implied license or other defenses to infringement that may 538 | otherwise be available to you under applicable patent law. 539 | 540 | 12. No Surrender of Others' Freedom. 541 | 542 | If conditions are imposed on you (whether by court order, agreement or 543 | otherwise) that contradict the conditions of this License, they do not 544 | excuse you from the conditions of this License. If you cannot convey a 545 | covered work so as to satisfy simultaneously your obligations under this 546 | License and any other pertinent obligations, then as a consequence you may 547 | not convey it at all. For example, if you agree to terms that obligate you 548 | to collect a royalty for further conveying from those to whom you convey 549 | the Program, the only way you could satisfy both those terms and this 550 | License would be to refrain entirely from conveying the Program. 551 | 552 | 13. Use with the GNU Affero General Public License. 553 | 554 | Notwithstanding any other provision of this License, you have 555 | permission to link or combine any covered work with a work licensed 556 | under version 3 of the GNU Affero General Public License into a single 557 | combined work, and to convey the resulting work. The terms of this 558 | License will continue to apply to the part which is the covered work, 559 | but the special requirements of the GNU Affero General Public License, 560 | section 13, concerning interaction through a network will apply to the 561 | combination as such. 562 | 563 | 14. Revised Versions of this License. 564 | 565 | The Free Software Foundation may publish revised and/or new versions of 566 | the GNU General Public License from time to time. Such new versions will 567 | be similar in spirit to the present version, but may differ in detail to 568 | address new problems or concerns. 569 | 570 | Each version is given a distinguishing version number. If the 571 | Program specifies that a certain numbered version of the GNU General 572 | Public License "or any later version" applies to it, you have the 573 | option of following the terms and conditions either of that numbered 574 | version or of any later version published by the Free Software 575 | Foundation. If the Program does not specify a version number of the 576 | GNU General Public License, you may choose any version ever published 577 | by the Free Software Foundation. 578 | 579 | If the Program specifies that a proxy can decide which future 580 | versions of the GNU General Public License can be used, that proxy's 581 | public statement of acceptance of a version permanently authorizes you 582 | to choose that version for the Program. 583 | 584 | Later license versions may give you additional or different 585 | permissions. However, no additional obligations are imposed on any 586 | author or copyright holder as a result of your choosing to follow a 587 | later version. 588 | 589 | 15. Disclaimer of Warranty. 590 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 599 | 600 | 16. Limitation of Liability. 601 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 610 | SUCH DAMAGES. 611 | 612 | 17. Interpretation of Sections 15 and 16. 613 | 614 | If the disclaimer of warranty and limitation of liability provided 615 | above cannot be given local legal effect according to their terms, 616 | reviewing courts shall apply local law that most closely approximates 617 | an absolute waiver of all civil liability in connection with the 618 | Program, unless a warranty or assumption of liability accompanies a 619 | copy of the Program in return for a fee. 620 | 621 | END OF TERMS AND CONDITIONS 622 | 623 | How to Apply These Terms to Your New Programs 624 | 625 | If you develop a new program, and you want it to be of the greatest 626 | possible use to the public, the best way to achieve this is to make it 627 | free software which everyone can redistribute and change under these terms. 628 | 629 | To do so, attach the following notices to the program. It is safest 630 | to attach them to the start of each source file to most effectively 631 | state the exclusion of warranty; and each file should have at least 632 | the "copyright" line and a pointer to where the full notice is found. 633 | 634 | 635 | Copyright (C) 2021 Protesilaos Stavrou 636 | 637 | This program is free software: you can redistribute it and/or modify 638 | it under the terms of the GNU General Public License as published by 639 | the Free Software Foundation, either version 3 of the License, or 640 | (at your option) any later version. 641 | 642 | This program is distributed in the hope that it will be useful, 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 645 | GNU General Public License for more details. 646 | 647 | You should have received a copy of the GNU General Public License 648 | along with this program. If not, see . 649 | 650 | Also add information on how to contact you by electronic and paper mail. 651 | 652 | If the program does terminal interaction, make it output a short 653 | notice like this when it starts in an interactive mode: 654 | 655 | Copyright (C) 2021 Protesilaos Stavrou 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 657 | This is free software, and you are welcome to redistribute it 658 | under certain conditions; type `show c' for details. 659 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate 661 | parts of the General Public License. Of course, your program's commands 662 | might be different; for a GUI interface, you would use an "about box". 663 | 664 | You should also get your employer (if you work as a programmer) or school, 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. 666 | For more information on this, and how to apply and follow the GNU GPL, see 667 | . 668 | 669 | The GNU General Public License does not permit incorporating your program 670 | into proprietary programs. If your program is a subroutine library, you 671 | may consider it more useful to permit linking proprietary applications with 672 | the library. If this is what you want to do, use the GNU Lesser General 673 | Public License instead of this License. But first, please read 674 | . 675 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Minibuffer Confines Transcended (mct.el) 2 | 3 | Enhancements for the default minibuffer completion UI of Emacs. In 4 | essence, MCT is (i) a very thin layer of interactivity on top of the 5 | out-of-the-box completion experience, and (ii) glue code that combines 6 | built-in functionalities to make the default completion framework work 7 | like that of more featureful third-party options. 8 | 9 | + Package name (GNU ELPA): `mct` 10 | + Official manual: 11 | + Change log: 12 | + Git repositories: 13 | + GitHub: 14 | + GitLab: 15 | + Video demo: 16 | + Backronym: Minibuffer Confines Transcended; Minibuffer and 17 | Completions in Tandem. 18 | -------------------------------------------------------------------------------- /README.org: -------------------------------------------------------------------------------- 1 | #+title: Minibuffer Confines Transcended (mct.el) 2 | #+author: Protesilaos Stavrou 3 | #+email: info@protesilaos.com 4 | #+language: en 5 | #+options: ':t toc:nil author:t email:t num:t 6 | #+startup: content 7 | #+macro: stable-version 1.0.0 8 | #+macro: release-date 2023-09-24 9 | #+macro: development-version 1.1.0-dev 10 | #+export_file_name: mct.texi 11 | #+texinfo_filename: mct.info 12 | #+texinfo_dir_category: Emacs misc features 13 | #+texinfo_dir_title: MCT: (mct) 14 | #+texinfo_dir_desc: Enhancement of the default minibuffer completion 15 | #+texinfo_header: @set MAINTAINERSITE @uref{https://protesilaos.com,maintainer webpage} 16 | #+texinfo_header: @set MAINTAINER Protesilaos Stavrou 17 | #+texinfo_header: @set MAINTAINEREMAIL @email{info@protesilaos.com} 18 | #+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:info@protesilaos.com,contact the maintainer} 19 | 20 | #+texinfo: @insertcopying 21 | 22 | This manual, written by Protesilaos Stavrou, describes the customization 23 | options for =mct= (or =mct.el= and variants), and provides every other piece 24 | of information pertinent to it. 25 | 26 | The documentation furnished herein corresponds to stable version 27 | {{{stable-version}}}, released on {{{release-date}}}. Any reference 28 | to a newer feature which does not yet form part of the latest tagged 29 | commit, is explicitly marked as such. 30 | 31 | Current development target is {{{development-version}}}. 32 | 33 | + Package name (GNU ELPA): ~mct~ 34 | + Official manual: 35 | + Change log: 36 | + Git repositories: 37 | + GitHub: 38 | + GitLab: 39 | + Video demo: 40 | + Backronym: Minibuffer Confines Transcended; Minibuffer and 41 | Completions in Tandem. 42 | 43 | If you are viewing the README.org version of this file, please note 44 | that the GNU ELPA machinery automatically generates an Info manual out 45 | of it. 46 | 47 | #+toc: headlines 8 insert TOC here, with eight headline levels 48 | 49 | * COPYING 50 | :PROPERTIES: 51 | :COPYING: t 52 | :CUSTOM_ID: h:efc32d6b-9405-4f3c-9560-3229b3ce3866 53 | :END: 54 | 55 | Copyright (C) 2021 Free Software Foundation, Inc. 56 | 57 | #+begin_quote 58 | Permission is granted to copy, distribute and/or modify this document 59 | under the terms of the GNU Free Documentation License, Version 1.3 or 60 | any later version published by the Free Software Foundation; with no 61 | Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and 62 | with the Back-Cover Texts as in (a) below. A copy of the license is 63 | included in the section entitled “GNU Free Documentation License.” 64 | 65 | (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and 66 | modify this GNU manual.” 67 | #+end_quote 68 | 69 | * Overview of MCT 70 | :PROPERTIES: 71 | :CUSTOM_ID: h:ba224631-618c-4e52-b373-e46970cb2242 72 | :END: 73 | #+cindex: Overview of features 74 | 75 | Minibuffer and Completions in Tandem, also known as "MCT", "Mct", =mct=, 76 | or =mct.el=, is a package that enhances the default minibuffer and 77 | =*Completions*= buffer of Emacs 28 (or higher) so that they work together 78 | as part of a unified framework. The idea is to make the presentation 79 | and overall functionality be consistent with other popular, vertically 80 | aligned completion UIs while leveraging built-in functionality. 81 | 82 | The main feature set that unifies the minibuffer and the =*Completions*= 83 | buffer consists of commands that cycle between the two, making it seem 84 | like they are part of a contiguous space ([[#h:884d6702-8666-4d89-87a2-7d74843653f3][Basic usage]]). 85 | 86 | MCT tries to find a middle ground between the frugal defaults and the 87 | more opinionated completion UIs. This is most evident in its approach 88 | on how to present completion candidates. Instead of showing them 89 | outright or only displaying them on demand, MCT implements a minimum 90 | input threshold as well as a slight delay before it pops up the 91 | =*Completions*= buffer and starts updating it to respond to user input. 92 | 93 | * Customizations 94 | :PROPERTIES: 95 | :CUSTOM_ID: h:6953b019-ab0c-4a08-8fd0-252c9cdb0dc2 96 | :END: 97 | 98 | MCT is highly configurable to adapt to the varying needs of users. This 99 | section documents each user option. 100 | 101 | ** Live completion 102 | :PROPERTIES: 103 | :CUSTOM_ID: h:1a85ed4c-f54d-482b-9915-563f60c64f15 104 | :END: 105 | #+vindex: mct-live-completion 106 | 107 | Brief: Control auto-display and live-update of the =*Completions*= buffer. 108 | 109 | Symbol: ~mct-live-completion~ (=choice= type) 110 | 111 | Possible values: 112 | 113 | 1. ~nil~ 114 | 2. ~t~ (default) 115 | 3. ~visible~ 116 | 117 | This user option governs the overall behaviour of MCT with regard to how 118 | it uses the Completions' buffer: 119 | 120 | + When nil, the user has to manually request completions, using the 121 | regular activating commands ([[#h:884d6702-8666-4d89-87a2-7d74843653f3][Usage]]). The Completions' buffer is never 122 | updated live to match user input. Updating has to be handled 123 | manually. This is like the out-of-the-box minibuffer completion 124 | experience. 125 | 126 | + When set to ~visible~, the Completions' buffer is live updated only if 127 | it is visible (present in a window). The actual display of the 128 | completions is still handled manually. For this reason, the ~visible~ 129 | style does not read the ~mct-minimum-input~, meaning that it will always 130 | try to live update the visible completions, regardless of input length 131 | ([[#h:ea15357e-c9d3-4840-84fe-1374c9f36e28][Minimum input threshold]]). 132 | 133 | + When non-nil (the default), the Completions' buffer is automatically 134 | displayed once the ~mct-minimum-input~ is met and is hidden if the input 135 | drops below that threshold. While visible, the buffer is updated live 136 | to match the user's input. 137 | 138 | Note that every command or completion category that is declared in the 139 | ~mct-completion-passlist~ ignores this option altogether. This means that 140 | every such symbol will always show the Completions' buffer automatically 141 | and will always update its contents live to match any further user input 142 | ([[#h:334abfc2-85ce-4519-add5-5a3775dd5e12][Passlist for commands or completion categories]]). Same principle for 143 | the ~mct-completion-blocklist~, which will always disable both the 144 | automatic display and live updating of the Completions' buffer 145 | ([[#h:36f56245-281a-4389-a998-66778de100db][Blocklist for commands or completion categories]]). 146 | 147 | [[#h:2fcf708f-4edf-41f3-9e29-0e750f3a80af][Size boundaries of the Completions]]. 148 | 149 | ** Minimum input threshold 150 | :PROPERTIES: 151 | :CUSTOM_ID: h:ea15357e-c9d3-4840-84fe-1374c9f36e28 152 | :END: 153 | #+vindex: mct-minimum-input 154 | 155 | Brief: Try to live update completions when input is >= N. 156 | 157 | Symbol: ~mct-minimum-input~ (=natnum= type) 158 | 159 | By default, MCT expects the user to type =3= characters before it tries to 160 | compute completion candidates, display the =*Completions*= buffer and keep 161 | it updated live to match any subsequent input. 162 | 163 | Setting this user option to a value greater than 1 can help reduce the 164 | total number of candidates that are being computed. That is because the 165 | Completions can consist of thousands of items that all need to be 166 | rendered at once in a buffer. 167 | 168 | In terms of the user experience, the minimum input threshold can make 169 | sessions feel less visually demanding when the user (i) knows what they 170 | are looking for and (ii) types fast enough so that the =*Completions*= 171 | never have the time to pop up. 172 | 173 | This variable is ignored for commands or completion categories that are 174 | specified in the ~mct-completion-passlist~ and ~mct-completion-blocklist~. 175 | 176 | [[#h:321ef12c-0f4a-440d-b88a-96e75325f3fc][Live updates per command or completion category]]. 177 | 178 | ** Delay between live updates 179 | :PROPERTIES: 180 | :CUSTOM_ID: h:e342534b-db28-4f7b-9f4d-f2b65ab5189e 181 | :END: 182 | #+vindex: mct-live-update-delay 183 | 184 | Brief: Delay in seconds before updating the Completions' buffer. 185 | 186 | Symbol: ~mct-live-update-delay~ (=number= type) 187 | 188 | The delay in seconds between live updates of the Completions' buffer. 189 | The default value is =0.3=. 190 | 191 | This variable is ignored for commands or completion categories that are 192 | specified in the ~mct-completion-passlist~ and ~mct-completion-blocklist~. 193 | 194 | [[#h:321ef12c-0f4a-440d-b88a-96e75325f3fc][Live updates per command or completion category]]. 195 | 196 | ** Live updates per command or completion category 197 | :PROPERTIES: 198 | :CUSTOM_ID: h:321ef12c-0f4a-440d-b88a-96e75325f3fc 199 | :END: 200 | #+cindex: Passlist and blocklist of commands or completion categories 201 | 202 | By default, MCT has the same behaviour across all types of completion. 203 | Specifically, it respects the ~mct-live-completion~ option on whether and 204 | when to perform live completion, the ~mct-minimum-input~ threshold before 205 | doing so, and the ~mct-live-update-delay~ between changes to the 206 | =*Completions*= buffer. 207 | 208 | [[#h:36f56245-281a-4389-a998-66778de100db][Live completion]]. 209 | 210 | [[#h:ea15357e-c9d3-4840-84fe-1374c9f36e28][Minimum input threshold]]. 211 | 212 | [[#h:e342534b-db28-4f7b-9f4d-f2b65ab5189e][Delay between live updates]]. 213 | 214 | A passlist and a blocklist can override those options for the commands 215 | or categories specified. 216 | 217 | *** Passlist for commands or completion categories 218 | :PROPERTIES: 219 | :CUSTOM_ID: h:334abfc2-85ce-4519-add5-5a3775dd5e12 220 | :END: 221 | #+vindex: mct-completion-passlist 222 | 223 | Brief: List of symbols where live completions are always enabled. 224 | 225 | Symbol: ~mct-completion-passlist~ (=repeat symbol= type) 226 | 227 | The value of this user option is a list of symbols. Those can refer to 228 | commands like ~find-file~ or completion categories such as ~file~, ~buffer~, 229 | or what other packages define like Consult's ~consult-location~ category. 230 | 231 | Any entry in the passlist ignores the value of ~mct-live-completion~ and 232 | the ~mct-minimum-input~. It also bypasses any possible delay introduced 233 | by ~mct-live-update-delay~. In other words, it immediately displays the 234 | =*Completions*= buffer and instantly updates it to match user input. 235 | 236 | When the ~mct-completion-blocklist~ and the ~mct-completion-passlist~ 237 | are in conflict, the former takes precedence. 238 | 239 | [[#h:1f42c4e6-53c1-4e8a-81ef-deab70822fa4][Known completion categories]]. 240 | 241 | *** Blocklist for commands or completion categories 242 | :PROPERTIES: 243 | :CUSTOM_ID: h:36f56245-281a-4389-a998-66778de100db 244 | :END: 245 | #+vindex: mct-completion-blocklist 246 | 247 | Brief: List of symbols where live completions are always disabled. 248 | 249 | Symbol: ~mct-completion-blocklist~ (=repeat symbol= type) 250 | 251 | The value of this user option is a list of symbols. Those can refer to 252 | commands like ~find-file~ or completion categories such as ~file~, ~buffer~, 253 | or what other packages define like Consult's ~consult-location~ category. 254 | 255 | This means that they ignore ~mct-live-completion~. They do not 256 | automatically display the Completions' buffer, nor do they update it to 257 | match user input. 258 | 259 | The Completions' buffer can still be accessed with commands that place 260 | it in a window (such as ~mct-list-completions-toggle~, 261 | ~mct-switch-to-completions-top~). 262 | 263 | When the ~mct-completion-blocklist~ and the ~mct-completion-passlist~ 264 | are in conflict, the former takes precedence. 265 | 266 | Perhaps a less drastic measure is to set ~mct-minimum-input~ to an 267 | appropriate value. Or better use ~mct-completion-passlist~. 268 | 269 | [[#h:1f42c4e6-53c1-4e8a-81ef-deab70822fa4][Known completion categories]]. 270 | 271 | *** Known completion categories 272 | :PROPERTIES: 273 | :CUSTOM_ID: h:1f42c4e6-53c1-4e8a-81ef-deab70822fa4 274 | :END: 275 | 276 | Below are the known completion categories that can be added to the 277 | ~mct-completion-passlist~ and ~mct-completion-blocklist~ (and relevant 278 | custom code). This resource is non-exhaustive and will be updated to 279 | match available information. 280 | 281 | + ~bookmark~ 282 | + ~buffer~ 283 | + ~charset~ 284 | + ~coding-system~ 285 | + ~color~ 286 | + ~command~ (e.g. =M-x=) 287 | + ~customize-group~ 288 | + ~environment-variable~ 289 | + ~expression~ 290 | + ~face~ 291 | + ~file~ 292 | + ~function~ (the ~describe-function~ command bound to =C-h f=) 293 | + ~info-menu~ 294 | + ~imenu~ 295 | + ~input-method~ 296 | + ~kill-ring~ 297 | + ~library~ 298 | + ~minor-mode~ 299 | + ~multi-category~ 300 | + ~package~ 301 | + ~project-file~ 302 | + ~symbol~ (the ~describe-symbol~ command bound to =C-h o=) 303 | + ~theme~ 304 | + ~unicode-name~ (the ~insert-char~ command bound to =C-x 8 RET=) 305 | + ~variable~ (the ~describe-variable~ command bound to =C-h v=) 306 | 307 | From the =consult= package: 308 | 309 | + ~consult-grep~ 310 | + ~consult-isearch~ 311 | + ~consult-isearch~ 312 | + ~consult-kmacro~ 313 | + ~consult-location~ 314 | 315 | From the =embark= package: 316 | 317 | + ~embark-keybinding~ 318 | 319 | In general, it is best not to add symbols which include several 320 | thousands of candidates to the passlist. So no ~command~, ~function~, 321 | ~symbol~, ~unicode-name~, ~variable~. 322 | 323 | When in doubt, do not add a symbol to either the pass- or block- list. 324 | 325 | [[#h:499ee65d-429d-48c0-9e3a-a60ca649e32d][Find completion category]]. 326 | 327 | *** Find completion category 328 | :PROPERTIES: 329 | :CUSTOM_ID: h:499ee65d-429d-48c0-9e3a-a60ca649e32d 330 | :END: 331 | 332 | While using a command that provides a minibuffer prompt, type =M-:= (the 333 | ~eval-expression~ command) and evaluate =(mct--completion-category)=. It 334 | will return the completion category, if any. Note that this only works 335 | when the variable ~enable-recursive-minibuffers~ is non-nil. 336 | 337 | To review echo area messages, use =C-h e= (~view-echo-area-messages~). 338 | 339 | [[#h:1f42c4e6-53c1-4e8a-81ef-deab70822fa4][Known completion categories]]. 340 | 341 | ** Size boundaries of the Completions 342 | :PROPERTIES: 343 | :CUSTOM_ID: h:2fcf708f-4edf-41f3-9e29-0e750f3a80af 344 | :END: 345 | #+vindex: mct-completion-window-size 346 | 347 | Brief: Set the maximum and minimum height of the Completions' buffer. 348 | 349 | Symbol: ~mct-completion-window-size~ (=choice= type between nil and cons cell) 350 | 351 | The value is a cons cell in the form of =(max-height . min-height)= where 352 | each value is either a natural number or a function which returns such a 353 | number. 354 | 355 | The default maximum height of the window is calculated by the function 356 | ~mct--frame-height-fraction~, which finds the closest round number to 357 | 1/3 of the frame's height. While the default minimum height is 1. This 358 | means that during live completions the Completions' window will shrink 359 | or grow to show candidates within the specified boundaries. To disable 360 | this bouncing effect, set both max-height and min-height to the same 361 | number. 362 | 363 | If nil, do not try to fit the Completions' buffer to its window. 364 | 365 | [[#h:1a85ed4c-f54d-482b-9915-563f60c64f15][Live completion]]. 366 | 367 | ** Hide the Completions mode line 368 | :PROPERTIES: 369 | :CUSTOM_ID: h:36adcbbb-f534-4595-9629-babe38a35efc 370 | :END: 371 | #+vindex: mct-hide-completion-mode-line 372 | 373 | Brief: Do not show a mode line in the Completions' buffer. 374 | 375 | Symbol: ~mct-hide-completion-mode-line~ (=boolean= type) 376 | 377 | By default, the =*Completions*= buffer has its own mode line, just like 378 | every other window. Set this user option to non-nil to remove the mode 379 | line. 380 | 381 | ** Remove shadowed file paths 382 | :PROPERTIES: 383 | :CUSTOM_ID: h:9d637155-04a5-419e-a9c5-471258130057 384 | :END: 385 | #+vindex: mct-remove-shadowed-file-name 386 | 387 | Brief: Delete shadowed parts of file names from the minibuffer. 388 | 389 | Symbol: ~mct-remove-shadowed-file-names~ (=boolean= type) 390 | 391 | When the built-in ~file-name-shadow-mode~ is enabled and this user option 392 | is non-nil, MCT will delete the part of the file path that is shadowed 393 | (meaning that it is overriden) by the given input. 394 | 395 | For example, if the user types =~/= after a long path name, everything 396 | preceding the =~/= is removed so the interactive selection process starts 397 | again from the user's =$HOME=. 398 | 399 | ** Show an indicator for ~completing-read-multiple~ prompts 400 | :PROPERTIES: 401 | :CUSTOM_ID: h:211065de-6ea8-4cfd-b0a2-c1f28a5ae341 402 | :END: 403 | #+vindex: mct-completing-read-multiple-indicator 404 | 405 | [ Part of {{{development-version}}}. ] 406 | 407 | Brief: Show an indicator for ~completing-read-multiple~ prompts. 408 | 409 | Symbol: ~mct-completing-read-multiple-indicator~ (=boolean= type) 410 | 411 | When non-nil show an indicator for ~completing-read-multiple~ prompts. 412 | If nil, do not show anything. Those prompts will look like the generic 413 | ones. 414 | 415 | The indicator informs the user this is a ~completing-read-multiple~ 416 | prompt and also shows the ~crm-separator~, which is usually a comma. 417 | 418 | ** MCT in the minibuffer and completion in regular buffers 419 | :PROPERTIES: 420 | :CUSTOM_ID: h:8109fe09-fcce-4212-88eb-943cc72f2c75 421 | :END: 422 | 423 | Emacs draws a distinction between two types of completion sessions: 424 | 425 | + Completion where the minibuffer is involved (such as to switch buffers 426 | or find a file). 427 | 428 | + Completion in a regular buffer to expand the text before point. The 429 | minibuffer is not active. We call this "in-buffer completion" or 430 | allude to the underlying function: ~completion-in-region~. 431 | 432 | #+findex: mct-mode 433 | The former scenario is what MCT has supported since its inception. 434 | Enable ~mct-mode~ to get started. There was a time where MCT also 435 | supported in-buffer completion but this was discontinued in version 436 | =1.0.0= of the package as Emacs 29 gained the requisite capabilities. 437 | To get the familiar MCT key bindings for in-buffer completion, use 438 | these in your init file: 439 | 440 | #+begin_src emacs-lisp 441 | ;; Define the small wrapper functions 442 | (defun my-mct-next-line-or-completion (n) 443 | "Select next completion or move to next line N times. 444 | Select the next completion if `completion-in-region-mode' is 445 | active and the Completions window is on display." 446 | (interactive "p") 447 | (if (and completion-in-region-mode (mct--get-completion-window)) 448 | (minibuffer-next-completion n) 449 | (next-line n))) 450 | 451 | (defun my-mct-previous-line-or-completion (n) 452 | "Select previous completion or move to previous line N times. 453 | Select the previous completion if `completion-in-region-mode' is 454 | active and the Completions window is on display." 455 | (interactive "p") 456 | (if (and completion-in-region-mode (mct--get-completion-window)) 457 | (minibuffer-previous-completion n) 458 | (previous-line n))) 459 | 460 | (defun my-mct-return-or-choose-completion (n) 461 | "Choose current completion or create N newlines. 462 | Choose the current completion if `completion-in-region-mode' is 463 | active and the Completions window is on display." 464 | (interactive "p") 465 | (if (and completion-in-region-mode (mct--get-completion-window)) 466 | (minibuffer-choose-completion) 467 | (newline n :interactive))) 468 | 469 | ;; Get the key bindings 470 | (let ((map completion-in-region-mode-map)) 471 | (define-key map (kbd "C-n") #'my-mct-next-line-or-completion) 472 | (define-key map (kbd "C-p") #'my-mct-previous-line-or-completion) 473 | (define-key map (kbd "RET") #'my-mct-return-or-choose-completion)) 474 | 475 | ;; Tweak the appearance 476 | (setq completions-format 'one-column) 477 | (setq completion-show-help nil) 478 | (setq completion-auto-help t) 479 | 480 | ;; Optionally, tweak the appearance further 481 | (setq completions-detailed t) 482 | (setq completion-show-inline-help nil) 483 | (setq completions-max-height 6) 484 | (setq completions-highlight-face 'completions-highlight) 485 | #+end_src 486 | 487 | Note that the in-buffer completions will produce a new buffer window 488 | below the current one. Some users find this intrusive. In such a 489 | case, the use of a popup box is better. Consider the ~corfu~ package 490 | by Daniel Mendler, which uses such a popup ([[#h:c9ddedea-e279-4233-94dc-f8d32367a954][Alternatives]]). 491 | 492 | * Usage 493 | :PROPERTIES: 494 | :CUSTOM_ID: h:884d6702-8666-4d89-87a2-7d74843653f3 495 | :END: 496 | 497 | This section outlines the various patterns of interaction that MCT 498 | establishes. 499 | 500 | ** Cyclic behaviour for mct-mode 501 | :PROPERTIES: 502 | :CUSTOM_ID: h:68c61a76-1d64-4f62-a77a-52e7b66a68fe 503 | :END: 504 | #+cindex: Cyclic behaviour in the minibuffer 505 | 506 | When ~mct-mode~ is enabled, some new keymaps are activated 507 | which add commands for cycling between the minibuffer and the 508 | completions. Suppose the following standard layout: 509 | 510 | #+begin_example 511 | ----------------- 512 | | | | 513 | | Buffers| Buf | 514 | | | | 515 | ----------------- 516 | | | | 517 | | Buf | Buf | 518 | | | | 519 | ----------------- 520 | ----------------- 521 | | | 522 | | Completions | 523 | | | 524 | ----------------- 525 | ----------------- 526 | | Minibuffer | 527 | ----------------- 528 | #+end_example 529 | 530 | #+findex: mct-switch-to-completions-top 531 | #+findex: mct-switch-to-completions-bottom 532 | When inside the minibuffer, pressing =C-n= (or down arrow) takes you to 533 | the top of the completions, while =C-p= (or up arrow) moves to the bottom. 534 | The commands are ~mct-switch-to-completions-top~ for the former and 535 | ~mct-switch-to-completions-bottom~ for the latter. If the =*Completions*= 536 | are not shown, then the buffer pops up automatically and point moves to 537 | the given position. 538 | 539 | #+findex: mct-previous-completion-or-mini 540 | #+findex: mct-next-completion-or-mini 541 | Similarly, while inside the =*Completions*= buffer, =C-p= (or up arrow) at 542 | the top of the buffer switches to the minibuffer, while =C-n= (or down 543 | arrow) at the bottom of the buffer also goes to the minibuffer. If 544 | point is anywhere else inside the buffer, those key bindings perform a 545 | regular line motion (if the =*Completions*= are set to a grid view, then 546 | the left and right arrow keys perform the corresponding lateral 547 | motions). The commands are ~mct-previous-completion-or-mini~ and 548 | ~mct-next-completion-or-mini~. Both accept an optional numeric argument. 549 | If the Nth line lies outside the boundaries of the completions' buffer, 550 | they move the point to the minibuffer. 551 | 552 | #+findex: mct-list-completions-toggle 553 | The display of the =*Completions*= can be toggled at any time from inside 554 | the minibuffer with =C-l= (mnemonic is "[l]ist completions" and the 555 | command is ~mct-list-completions-toggle~). 556 | 557 | ** Selecting candidates with mct-mode 558 | :PROPERTIES: 559 | :CUSTOM_ID: h:bb445062-2e39-4082-a868-2123bfb793cc 560 | :END: 561 | #+cindex: Candidate selection for minibuffer completion 562 | 563 | There are several ways to select a completion candidate with 564 | ~mct-mode~. 565 | 566 | 1. Suppose that you are typing =mod= with the intent to select the 567 | =modus-themes.el= buffer. To complete the candidate follow up =mod= with 568 | the =TAB= key (~minibuffer-complete~). If the match is unique, the text 569 | will be expanded. Otherwise the =*Completions*= buffer will appear. 570 | This does not exit the minibuffer, meaning that it does not confirm 571 | your choice. To confirm your choice, use =RET=. If you ever make a 572 | mistake and expand the wrong candidate, just use ~undo~. Lastly note 573 | that if the candidates meet the ~completion-cycle-threshold~ hitting 574 | =TAB= again will switch between them. 575 | 576 | #+findex: mct-choose-completion-exit 577 | 2. While cycling through the completions' buffer, type =RET= to select and 578 | confirm the current candidate (~mct-choose-completion-exit~). This 579 | works for all types of completion prompts. 580 | 581 | #+findex: mct-choose-completion-no-exit 582 | 3. Similar to the above, but without exiting the minibuffer (i.e. to 583 | confirm your choice) is ~mct-choose-completion-no-exit~ which is bound 584 | to =TAB= in the completions' buffer. This is particularly useful for 585 | certain contexts where selecting a candidate does not necessarily 586 | mean that the process has to be finalised (e.g. when using 587 | ~find-file~). In those cases, the event triggered by =TAB= is followed 588 | by the renewal of the list of completions, where relevant (e.g. =TAB= 589 | over a directory in ~find-file~, which then shows the contents of that 590 | directory). 591 | 592 | The command can correctly expand completion candidates even when the 593 | active style in ~completion-styles~ is =partial-completion=. In other 594 | words, if the minibuffer contains input like =~/G/P/m= and the point is 595 | in the completions' buffer over =Git/Projects/mct/= the minibuffer' 596 | contents will become =~/Git/Projects/mct/= and then show the contents 597 | of that directory. 598 | 599 | #+findex: mct-edit-completion 600 | 4. Type =M-e= (~mct-edit-completion~) in the completions' buffer to place 601 | the current candidate in the minibuffer, without exiting the session. 602 | This allows you to edit the text before confirming it. If point is 603 | in the minibuffer before performing this action, the current 604 | candidate is either the one at the top of the completions' buffer or 605 | that which is under the last known point in said buffer (the last 606 | known position is reset when the window is deleted). Internally, 607 | ~mct-edit-completion~ uses ~mct-choose-completion-no-exit~ to expand the 608 | completion candidate, so it retains its behaviour (as explained right 609 | above). 610 | 611 | #+findex: mct-focus-minibuffer 612 | Sometimes there is a need to switch to the minibuffer without 613 | selecting the candidate at point, such as to retype some part of the 614 | input. In those cases, type =e= in the completions' buffer to move to 615 | the minibuffer. The command is called ~mct-focus-minibuffer~, which 616 | can also be assigned to the global keymap, though MCT leaves such a 617 | decision up to the user (same for ~mct-focus-mini-or-completions~). 618 | 619 | #+findex: mct-choose-completion-dwim 620 | 5. In prompts that allow the selection of multiple candidates 621 | (internally via the ~completing-read-multiple~ function) using =M-RET= 622 | (~mct-choose-completion-dwim~) in the =*Completions*= will append the 623 | candidate at point to the list of selections and keep the completions 624 | available so that another item may be selected. Any of the 625 | aforementioned applicable methods can confirm the final selection. 626 | If, say, you want to pick a total of three candidates, do =M-RET= for 627 | the first two and =RET= (~mct-choose-completion-exit~) for the last one. 628 | In contexts that are not CRM-powered, the =M-RET= has the same effect 629 | as =TAB= (~mct-choose-completion-no-exit~). 630 | 631 | [[#h:162f232d-1e9d-4756-90d3-d6bf5bb4d8ef][Indicator for completing-read-multiple]]. 632 | 633 | #+findex: mct-complete-and-exit 634 | 6. When point is at the minibuffer, select the current candidate in 635 | the completions buffer with =C-RET= (~mct-complete-and-exit~), which 636 | has the same effect as first completing with =TAB= and then 637 | immediately exit the minibuffer with the completed candidate as the 638 | selected one. 639 | 640 | #+findex: mct-next-completion-group 641 | #+findex: mct-previous-completion-group 642 | 7. Emacs 28 has the ability to group candidates inside the completions' 643 | buffer under headings. For example, the Consult package makes use of 644 | those ([[#h:03227254-d467-4147-b8cf-2fe05a2e279b][Third-party extensions]]). MCT provides motions that jump 645 | between such headings, placing the point at the first candidate right 646 | below the heading's text. Use =M-n= (~mct-next-completion-group~) 647 | and =M-p= (~mct-previous-completion-group~) to move to the next or 648 | previous one, respectively (also work with they keys for 649 | ~forward-paragraph~ and ~backward-paragraph~). Both commands accept 650 | an optional numeric argument. For the sake of avoiding surprises, 651 | these commands do not cycle between the completions and the 652 | minibuffer: they stop at the first or last heading. 653 | 654 | * Installation 655 | :PROPERTIES: 656 | :CUSTOM_ID: h:1b501ed4-f16c-4118-9a4a-7a5e29143077 657 | :END: 658 | 659 | ** Install the package 660 | :PROPERTIES: 661 | :CUSTOM_ID: h:a191dbaa-22f6-4ad6-8185-1de64fe0a9bc 662 | :END: 663 | 664 | =mct= is available on the official GNU ELPA archive for users of Emacs 665 | version 27 or higher. One can install the package without any further 666 | configuration. The following commands shall suffice: 667 | 668 | #+begin_src emacs-lisp 669 | M-x package-refresh-contents 670 | M-x package-install RET mct 671 | #+end_src 672 | 673 | A package is also available via Guix: 674 | 675 | #+begin_src sh 676 | guix package -i emacs-mct 677 | #+end_src 678 | 679 | ** Manual installation method 680 | :PROPERTIES: 681 | :CUSTOM_ID: h:663ec536-056b-443e-9272-2a365eb28b83 682 | :END: 683 | 684 | Assuming your Emacs files are found in =~/.emacs.d/=, execute the 685 | following commands in a shell prompt: 686 | 687 | #+begin_src sh 688 | cd ~/.emacs.d 689 | 690 | # Create a directory for manually-installed packages 691 | mkdir manual-packages 692 | 693 | # Go to the new directory 694 | cd manual-packages 695 | 696 | # Clone this repo and name it "mct" 697 | git clone https://github.com/protesilaos/mct mct 698 | #+end_src 699 | 700 | Finally, in your =init.el= (or equivalent) evaluate this: 701 | 702 | #+begin_src emacs-lisp 703 | ;; Make Elisp files in that directory available to the user. 704 | (add-to-list 'load-path "~/.emacs.d/manual-packages/mct") 705 | #+end_src 706 | 707 | Everything is in place to set up the package. 708 | 709 | * Sample setup 710 | :PROPERTIES: 711 | :CUSTOM_ID: h:318ba6f8-2909-44b0-9bed-558552722667 712 | :END: 713 | #+cindex: Sample configuration 714 | 715 | Minimal setup for the minibuffer and in-buffer completion: 716 | 717 | #+begin_src emacs-lisp 718 | (require 'mct) 719 | (mct-mode 1) 720 | #+end_src 721 | 722 | And with more options: 723 | 724 | #+begin_src emacs-lisp 725 | (require 'mct) 726 | 727 | (setq mct-completion-window-size (cons #'mct-frame-height-third 1)) 728 | (setq mct-remove-shadowed-file-names t) ; works when `file-name-shadow-mode' is enabled 729 | (setq mct-hide-completion-mode-line t) 730 | (setq mct-completing-read-multiple-indicator t) 731 | (setq mct-minimum-input 3) 732 | (setq mct-live-completion t) 733 | (setq mct-live-update-delay 0.6) 734 | 735 | ;; This is for commands or completion categories that should always pop 736 | ;; up the completions' buffer. It circumvents the default method of 737 | ;; waiting for some user input (see `mct-minimum-input') before 738 | ;; displaying and updating the completions' buffer. 739 | (setq mct-completion-passlist 740 | '(;; Some commands 741 | Info-goto-node 742 | Info-index 743 | Info-menu 744 | vc-retrieve-tag 745 | ;; Some completion categories 746 | imenu 747 | file 748 | project-file 749 | buffer 750 | kill-ring 751 | consult-location)) 752 | 753 | ;; The blocklist follows the same principle as the passlist, except it 754 | ;; disables live completions altogether. 755 | (setq mct-completion-blocklist nil) 756 | 757 | (mct-mode 1) 758 | #+end_src 759 | 760 | Other useful extras from the Emacs source code (read their doc strings): 761 | 762 | #+begin_src emacs-lisp 763 | (setq completion-styles 764 | '(basic substring initials flex partial-completion)) 765 | (setq completion-category-overrides 766 | '((file (styles . (basic partial-completion initials substring))))) 767 | 768 | (setq completion-cycle-threshold 2) 769 | (setq completion-ignore-case t) 770 | (setq completion-show-inline-help nil) 771 | 772 | (setq completions-detailed t) 773 | 774 | (setq enable-recursive-minibuffers t) 775 | (setq minibuffer-eldef-shorten-default t) 776 | 777 | (setq read-buffer-completion-ignore-case t) 778 | (setq read-file-name-completion-ignore-case t) 779 | 780 | (setq resize-mini-windows t) 781 | (setq minibuffer-eldef-shorten-default t) 782 | 783 | (file-name-shadow-mode 1) 784 | (minibuffer-depth-indicate-mode 1) 785 | (minibuffer-electric-default-mode 1) 786 | 787 | ;; Do not allow the cursor in the minibuffer prompt 788 | (setq minibuffer-prompt-properties 789 | '(read-only t cursor-intangible t face minibuffer-prompt)) 790 | 791 | (add-hook 'minibuffer-setup-hook #'cursor-intangible-mode) 792 | 793 | ;;; Minibuffer history 794 | (require 'savehist) 795 | (setq savehist-file (locate-user-emacs-file "savehist")) 796 | (setq history-length 500) 797 | (setq history-delete-duplicates t) 798 | (setq savehist-save-minibuffer-history t) 799 | (add-hook 'after-init-hook #'savehist-mode) 800 | 801 | ;;; Third-party extensions 802 | 803 | ;;;; Enable Consult previews in the Completions buffer. 804 | ;; Requires the `consult' package. 805 | (add-hook 'completion-list-mode-hook #'consult-preview-at-point-mode) 806 | 807 | ;;;; Setup for Orderless 808 | ;; Requires the `orderless' package 809 | 810 | ;; We make the SPC key insert a literal space and the same for the 811 | ;; question mark. Spaces are used to delimit orderless groups, while 812 | ;; the quedtion mark is a valid regexp character. 813 | (let ((map minibuffer-local-completion-map)) 814 | (define-key map (kbd "SPC") nil) 815 | (define-key map (kbd "?") nil)) 816 | 817 | ;; Because SPC works for Orderless and is trivial to activate, I like to 818 | ;; put `orderless' at the end of my `completion-styles'. Like this: 819 | (setq completion-styles 820 | '(basic substring initials flex partial-completion orderless)) 821 | (setq completion-category-overrides 822 | '((file (styles . (basic partial-completion orderless))))) 823 | #+end_src 824 | 825 | * Keymaps 826 | :PROPERTIES: 827 | :CUSTOM_ID: h:b3178edd-f340-444c-8426-fe84f23ac9ea 828 | :END: 829 | #+cindex: Keymaps 830 | #+vindex: mct-completion-list-mode-map 831 | #+vindex: mct-minibuffer-local-completion-map 832 | 833 | MCT defines its own keymaps, which extend those that are active in the 834 | minibuffer and the =*Completions*= buffer, respectively: 835 | 836 | + ~mct-completion-list-mode-map~ 837 | + ~mct-minibuffer-local-completion-map~ 838 | 839 | You can invoke ~describe-keymap~ to learn more about them. 840 | 841 | If you want to edit any key bindings, do it in these keymaps, not in 842 | those they extend and override (the names of the original ones are the 843 | same as above, minus the =mct-= prefix). 844 | 845 | * User-level tweaks or custom code 846 | :PROPERTIES: 847 | :CUSTOM_ID: h:2630a7a3-1b11-4e9d-8282-0ea3bf9e2a5b 848 | :END: 849 | #+cindex: Custom tweaks or extensions 850 | 851 | In this section we cover custom code that builds on what MCT offers. 852 | 853 | ** Sort completion candidates on Emacs 29 854 | :PROPERTIES: 855 | :CUSTOM_ID: h:493922c7-efdc-4b63-aa96-b31c684eb4fa 856 | :END: 857 | #+cindex: Sorting completions 858 | 859 | Starting with Emacs 29 (current development target), the user option 860 | ~completions-sort~ controls the sorting method of candidates in the 861 | =*Completions*= buffer. Beside the default of using ~string-lessp~, it 862 | accepts a custom function. Consider any of the following examples: 863 | 864 | #+begin_src emacs-lisp 865 | ;; Some sorting functions... 866 | (defun my-sort-by-alpha-length (elems) 867 | "Sort ELEMS first alphabetically, then by length." 868 | (sort elems (lambda (c1 c2) 869 | (or (string-version-lessp c1 c2) 870 | (< (length c1) (length c2)))))) 871 | 872 | (defun my-sort-by-history (elems) 873 | "Sort ELEMS by minibuffer history. 874 | Use `mct-sort-sort-by-alpha-length' if no history is available." 875 | (if-let ((hist (and (not (eq minibuffer-history-variable t)) 876 | (symbol-value minibuffer-history-variable)))) 877 | (minibuffer--sort-by-position hist elems) 878 | (my-sort-by-alpha-length elems))) 879 | 880 | (defun my-sort-multi-category (elems) 881 | "Sort ELEMS per completion category." 882 | (pcase (mct--completion-category) 883 | ('nil elems) ; no sorting 884 | ('kill-ring elems) 885 | ('project-file (my-sort-by-alpha-length elems)) 886 | (_ (my-sort-by-history elems)))) 887 | 888 | ;; Specify the sorting function. 889 | (setq completions-sort #'my-sort-multi-category) 890 | #+end_src 891 | 892 | [[#h:1f42c4e6-53c1-4e8a-81ef-deab70822fa4][Known completion categories]]. 893 | 894 | ** Indicator for completing-read-multiple 895 | :PROPERTIES: 896 | :CUSTOM_ID: h:162f232d-1e9d-4756-90d3-d6bf5bb4d8ef 897 | :END: 898 | #+cindex: CRM indicator 899 | 900 | [ As part of {{{development-version}}}, this feature is built into the 901 | MCT code ([[#h:211065de-6ea8-4cfd-b0a2-c1f28a5ae341][Show an indicator for ~completing-read-multiple~ prompts]]). 902 | I decided that it is better to have it on by default, otherwise the 903 | ~completing-read-multiple~ prompts are hard to identify. ] 904 | 905 | Previous versions of MCT would prepend a =[CRM]= tag to the minibuffer 906 | prompt of commands powered by ~completing-read-multiple~. While this is a 907 | nice usability enhancement, it is not specific to MCT and thus should 908 | not be part of =mct.el=. Use this in your init file instead: 909 | 910 | #+begin_src emacs-lisp 911 | ;; Add prompt indicator to `completing-read-multiple'. We display 912 | ;; [`completing-read-multiple': ], e.g., 913 | ;; [`completing-read-multiple': ,] if the separator is a comma. This 914 | ;; is adapted from the README of the `vertico' package by Daniel 915 | ;; Mendler. I made some small tweaks to propertize the segments of 916 | ;; the prompt. 917 | (defun crm-indicator (args) 918 | (cons (format "[`crm-separator': %s] %s" 919 | (propertize 920 | (replace-regexp-in-string 921 | "\\`\\[.*?]\\*\\|\\[.*?]\\*\\'" "" 922 | crm-separator) 923 | 'face 'error) 924 | (car args)) 925 | (cdr args))) 926 | 927 | (advice-add #'completing-read-multiple :filter-args #'crm-indicator) 928 | #+end_src 929 | 930 | ** Ido-style navigation through directories 931 | :PROPERTIES: 932 | :CUSTOM_ID: h:9a6746dd-0be9-4e29-ac40-0af9612d05a2 933 | :END: 934 | 935 | Older versions of MCT had a command for file navigation that would 936 | delete the whole directory component before point, effectively going 937 | back up one directory. While the functionality can be useful, it is not 938 | integral to the MCT experience and thus should not belong in =mct.el=. 939 | Add this to your own configuration file instead: 940 | 941 | #+begin_src emacs-lisp 942 | ;; Adaptation of `icomplete-fido-backward-updir'. 943 | (defun my-backward-updir () 944 | "Delete char before point or go up a directory." 945 | (interactive nil mct-mode) 946 | (cond 947 | ((and (eq (char-before) ?/) 948 | (eq (mct--completion-category) 'file)) 949 | (when (string-equal (minibuffer-contents) "~/") 950 | (delete-minibuffer-contents) 951 | (insert (expand-file-name "~/")) 952 | (goto-char (line-end-position))) 953 | (save-excursion 954 | (goto-char (1- (point))) 955 | (when (search-backward "/" (minibuffer-prompt-end) t) 956 | (delete-region (1+ (point)) (point-max))))) 957 | (t (call-interactively 'backward-delete-char)))) 958 | 959 | (define-key minibuffer-local-filename-completion-map (kbd "DEL") #'my-backward-updir) 960 | #+end_src 961 | 962 | * Third-party extensions 963 | :PROPERTIES: 964 | :CUSTOM_ID: h:03227254-d467-4147-b8cf-2fe05a2e279b 965 | :END: 966 | #+cindex: Extra packages 967 | 968 | MCT only tweaks the default minibuffer. To get more out of it, consider 969 | these exceptionally well-crafted extras: 970 | 971 | + [[https://github.com/minad/consult/][Consult]] by Daniel Mendler :: Adds several commands that make 972 | interacting with the minibuffer more powerful. There also are 973 | multiple packages that build on it, such as [[https://github.com/karthink/consult-dir][consult-dir]] by Karthik 974 | Chikmagalur and [[https://codeberg.org/jao/consult-notmuch][consult-notmuch]] by José Antonio Ortega Ruiz. 975 | 976 | + [[https://github.com/oantolin/embark/][Embark]] by Omar Antolín Camarena :: Provides configurable contextual 977 | actions for completions and many other constructs inside buffers. A 978 | genius package! 979 | 980 | + [[https://github.com/minad/marginalia][Marginalia]] by Daniel and Omar :: Displays informative annotations for 981 | all known types of completion candidates. 982 | 983 | + [[https://github.com/oantolin/orderless/][Orderless]] by Omar :: A completion style that matches a variety of 984 | patterns (regexp, flex, initialism, etc.) regardless of the order they 985 | appear in. 986 | 987 | + [[https://github.com/iyefrat/all-the-icons-completion][all-the-icons-completion]] by Itai Y. Efrat :: Glue code that adds icons 988 | from the =all-the-icons= package to the =*Completions*= buffer. It can 989 | make things prettier and/or more informative, while it can also be 990 | combined with Marginalia. 991 | 992 | MCT does not support the use-case of ~completion-in-region~. This is 993 | the kind of completion session that is done inside the buffer and does 994 | not involve the minibuffer. However, you may prefer: 995 | 996 | + [[https://github.com/minad/corfu/][Corfu]] by Daniel Mendler :: An interface for the ~completion-in-region~ 997 | which uses a child frame (basically a pop-up) at the position of the 998 | cursor to display candidates. As with all of Daniel's packages, Corfu 999 | aims for a clean implementation that does the right thing by being 1000 | consistent with core Emacs mechanisms. 1001 | 1002 | + [[https://github.com/minad/cape][Cape]] also by Daniel :: Additional ~completion-at-point-functions~ 1003 | (CAPFs) that extend those of core Emacs. These backends can be used 1004 | by packages that visualise ~completion-in-region~. 1005 | 1006 | ** Enable Consult previews 1007 | :PROPERTIES: 1008 | :CUSTOM_ID: h:85268cb1-9d49-452c-ba5f-c9215d4b8b62 1009 | :END: 1010 | 1011 | One of the nice features of the Consult package is the ability to 1012 | preview the candidate at point. All we need to enable it in the 1013 | =*Completions*= buffer is the following snippet: 1014 | 1015 | #+begin_src emacs-lisp 1016 | (add-hook 'completion-list-mode-hook #'consult-preview-at-point-mode) 1017 | #+end_src 1018 | 1019 | * Alternatives 1020 | :PROPERTIES: 1021 | :CUSTOM_ID: h:c9ddedea-e279-4233-94dc-f8d32367a954 1022 | :END: 1023 | #+cindex: Alternatives to MCT 1024 | 1025 | In the grand scheme of things, it may be helpful to think of MCT as 1026 | proof-of-concept on how the default Emacs completion can become more 1027 | expressive. MCT's value rests in its potential to inspire developers to 1028 | (i) patch Emacs so that its out-of-the-box completion is more 1029 | interactive, and (ii) expose the shortcomings in the current 1030 | implementation of the =*Completions*= buffer, which should again provide 1031 | an impetus for further changes to Emacs. Otherwise, MCT is meant for 1032 | users who can tolerate the status quo and simply want a thin layer of 1033 | interactivity for minibuffer completion, in-buffer completion, and their 1034 | intersection with the Completions' buffer. 1035 | 1036 | Like MCT, these alternatives provide a thin layer of functionality over 1037 | the built-in infrastructure. Unlike MCT, they are not constrained by 1038 | the design of the =*Completions*= buffer and concomitant functionality. 1039 | They all make for a natural complement to the standard Emacs experience 1040 | (also [[#h:03227254-d467-4147-b8cf-2fe05a2e279b][Extensions]]). 1041 | 1042 | + [[https://github.com/minad/vertico][Vertico]] by Daniel Mendler :: this is a more mature and feature-rich 1043 | package with a large user base and a highly competent maintainer. 1044 | 1045 | Vertico has some performance optimizations on how candidates are 1046 | sorted and presented, which means that it displays results right away 1047 | without any noticeable performance penalty. Whereas MCT does not 1048 | change the underlying behaviour of how candidates are displayed. As 1049 | such, MCT will be slower in scenaria where there are lots of 1050 | candidates because core Emacs lacks those optimizations. One such 1051 | case is with the ~describe-symbol~ (=C-h o=) prompt. If the user asks for 1052 | the completions' buffer without inputting any character (so without 1053 | narrowing the list), there will be a noticeable delay before the 1054 | buffer is rendered. This is mitigated in MCT by the requirement for 1055 | ~mct-minimum-input~, though the underlying mechanics remain intact. 1056 | 1057 | In terms of the interaction model, the main difference between Vertico 1058 | and MCT is that the former uses the minibuffer by default and shows 1059 | the completions there. The minibuffer is expanded to show the 1060 | candidates in a vertical list. Whereas MCT keeps the =*Completions*= 1061 | buffer and the minibuffer as separate entities, the way standard Emacs 1062 | does it. 1063 | 1064 | The presence of a fully fledged buffer means that the user can invoke 1065 | all relevant commands at their disposal, such as to write the buffer 1066 | to a file for future review, use Isearch to move around, copy a string 1067 | or rectangle to a register, and so on. 1068 | 1069 | Vertico has official extensions which can make it work exactly like 1070 | MCT without any of MCT's drawbacks. These extensions can also expand 1071 | Vertico's powers such as by providing granular control over the exact 1072 | style of presentation for any given completion category (e.g. display 1073 | Imenu in a separate buffer, show the ~switch-to-buffer~ list 1074 | horizontally in the minibuffer, and present ~find-file~ in a vertical 1075 | list---whatever the user wants). 1076 | 1077 | All things considered, there is no compelling reason why one may 1078 | prefer MCT over Vertico in terms of the available functionality: 1079 | Vertico is better. 1080 | 1081 | + Icomplete and fido-mode (built-in, multiple authors) :: Icomplete is 1082 | closer in spirit to Vertico, as it too uses the minibuffer to display 1083 | completion candidates. By default, it presents the list horizontally, 1084 | though there exists ~icomplete-vertical-mode~ (and ~fido-vertical-mode~). 1085 | 1086 | For our purposes, Icomplete and Fido are the same in terms of the 1087 | paradigm they follow. The latter is a re-spin of the former, as it 1088 | adjusts certain variables and binds some commands for the convenience 1089 | of the end-user. ~fido-mode~ and its accoutrements are defined in 1090 | =icomplete.el=. 1091 | 1092 | What MCT borrows from Icomplete is for the input delay (explained 1093 | elsewhere in this document). Internally, I also learnt how to extend 1094 | local keymaps by studying =icomplete.el=. 1095 | 1096 | I had used Icomplete for several months before moving to what now has 1097 | become =mct.el=. I think it is excellent at providing a thin layer over 1098 | the built-in infrastructure. 1099 | 1100 | * Acknowledgements 1101 | :PROPERTIES: 1102 | :CUSTOM_ID: h:e2f73255-55f1-4f4c-8d8b-99c9a4a83192 1103 | :END: 1104 | #+cindex: Contributors 1105 | 1106 | MCT is meant to be a collective effort. Every bit of help matters. 1107 | 1108 | + Author/maintainer :: Protesilaos Stavrou. 1109 | 1110 | + Contributions to code or documentation :: Daniel Mendler, James 1111 | Norman Vladimir Cash, Jessie Hu, José Antonio Ortega Ruiz, Juri 1112 | Linkov, Philip Kaludercic, Tomasz Hołubowicz. 1113 | 1114 | + Ideas and user feedback :: Andrew Tropin, Benjamin (@zealotrush), Case 1115 | Duckworth, Chris Burroughs, Jonathan Irving, José Antonio Ortega Ruiz, 1116 | Kostadin Ninev, Manuel Uberti, Morgan Willcock, Philip Kaludercic, 1117 | Theodor Thornhill, Tomasz Hołubowicz, Z.Du. As well as users: 1118 | danrobi11. 1119 | 1120 | + Packaging :: Andrew Tropin and Nicolas Goaziou (Guix). 1121 | 1122 | + Inspiration for certain features :: =icomplete.el= (built-in---multiple 1123 | authors), Daniel Mendler (=vertico=), Omar Antolín Camarena (=embark=, 1124 | =live-completions=). 1125 | 1126 | * Official sources 1127 | :PROPERTIES: 1128 | :CUSTOM_ID: h:32f474f2-f596-4a7e-a0da-023344136be1 1129 | :END: 1130 | 1131 | + Manual :: 1132 | + Change log :: 1133 | + Source code :: 1134 | + Mailing list :: 1135 | 1136 | * GNU Free Documentation License 1137 | :PROPERTIES: 1138 | :APPENDIX: t 1139 | :CUSTOM_ID: h:2d84e73e-c143-43b5-b388-a6765da974ea 1140 | :END: 1141 | 1142 | #+texinfo: @include doclicense.texi 1143 | 1144 | #+begin_export html 1145 | 
1146 | 
1147 |                 GNU Free Documentation License
1148 |                  Version 1.3, 3 November 2008
1149 | 
1150 | 
1151 |  Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
1152 |      
1153 |  Everyone is permitted to copy and distribute verbatim copies
1154 |  of this license document, but changing it is not allowed.
1155 | 
1156 | 0. PREAMBLE
1157 | 
1158 | The purpose of this License is to make a manual, textbook, or other
1159 | functional and useful document "free" in the sense of freedom: to
1160 | assure everyone the effective freedom to copy and redistribute it,
1161 | with or without modifying it, either commercially or noncommercially.
1162 | Secondarily, this License preserves for the author and publisher a way
1163 | to get credit for their work, while not being considered responsible
1164 | for modifications made by others.
1165 | 
1166 | This License is a kind of "copyleft", which means that derivative
1167 | works of the document must themselves be free in the same sense.  It
1168 | complements the GNU General Public License, which is a copyleft
1169 | license designed for free software.
1170 | 
1171 | We have designed this License in order to use it for manuals for free
1172 | software, because free software needs free documentation: a free
1173 | program should come with manuals providing the same freedoms that the
1174 | software does.  But this License is not limited to software manuals;
1175 | it can be used for any textual work, regardless of subject matter or
1176 | whether it is published as a printed book.  We recommend this License
1177 | principally for works whose purpose is instruction or reference.
1178 | 
1179 | 
1180 | 1. APPLICABILITY AND DEFINITIONS
1181 | 
1182 | This License applies to any manual or other work, in any medium, that
1183 | contains a notice placed by the copyright holder saying it can be
1184 | distributed under the terms of this License.  Such a notice grants a
1185 | world-wide, royalty-free license, unlimited in duration, to use that
1186 | work under the conditions stated herein.  The "Document", below,
1187 | refers to any such manual or work.  Any member of the public is a
1188 | licensee, and is addressed as "you".  You accept the license if you
1189 | copy, modify or distribute the work in a way requiring permission
1190 | under copyright law.
1191 | 
1192 | A "Modified Version" of the Document means any work containing the
1193 | Document or a portion of it, either copied verbatim, or with
1194 | modifications and/or translated into another language.
1195 | 
1196 | A "Secondary Section" is a named appendix or a front-matter section of
1197 | the Document that deals exclusively with the relationship of the
1198 | publishers or authors of the Document to the Document's overall
1199 | subject (or to related matters) and contains nothing that could fall
1200 | directly within that overall subject.  (Thus, if the Document is in
1201 | part a textbook of mathematics, a Secondary Section may not explain
1202 | any mathematics.)  The relationship could be a matter of historical
1203 | connection with the subject or with related matters, or of legal,
1204 | commercial, philosophical, ethical or political position regarding
1205 | them.
1206 | 
1207 | The "Invariant Sections" are certain Secondary Sections whose titles
1208 | are designated, as being those of Invariant Sections, in the notice
1209 | that says that the Document is released under this License.  If a
1210 | section does not fit the above definition of Secondary then it is not
1211 | allowed to be designated as Invariant.  The Document may contain zero
1212 | Invariant Sections.  If the Document does not identify any Invariant
1213 | Sections then there are none.
1214 | 
1215 | The "Cover Texts" are certain short passages of text that are listed,
1216 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that
1217 | the Document is released under this License.  A Front-Cover Text may
1218 | be at most 5 words, and a Back-Cover Text may be at most 25 words.
1219 | 
1220 | A "Transparent" copy of the Document means a machine-readable copy,
1221 | represented in a format whose specification is available to the
1222 | general public, that is suitable for revising the document
1223 | straightforwardly with generic text editors or (for images composed of
1224 | pixels) generic paint programs or (for drawings) some widely available
1225 | drawing editor, and that is suitable for input to text formatters or
1226 | for automatic translation to a variety of formats suitable for input
1227 | to text formatters.  A copy made in an otherwise Transparent file
1228 | format whose markup, or absence of markup, has been arranged to thwart
1229 | or discourage subsequent modification by readers is not Transparent.
1230 | An image format is not Transparent if used for any substantial amount
1231 | of text.  A copy that is not "Transparent" is called "Opaque".
1232 | 
1233 | Examples of suitable formats for Transparent copies include plain
1234 | ASCII without markup, Texinfo input format, LaTeX input format, SGML
1235 | or XML using a publicly available DTD, and standard-conforming simple
1236 | HTML, PostScript or PDF designed for human modification.  Examples of
1237 | transparent image formats include PNG, XCF and JPG.  Opaque formats
1238 | include proprietary formats that can be read and edited only by
1239 | proprietary word processors, SGML or XML for which the DTD and/or
1240 | processing tools are not generally available, and the
1241 | machine-generated HTML, PostScript or PDF produced by some word
1242 | processors for output purposes only.
1243 | 
1244 | The "Title Page" means, for a printed book, the title page itself,
1245 | plus such following pages as are needed to hold, legibly, the material
1246 | this License requires to appear in the title page.  For works in
1247 | formats which do not have any title page as such, "Title Page" means
1248 | the text near the most prominent appearance of the work's title,
1249 | preceding the beginning of the body of the text.
1250 | 
1251 | The "publisher" means any person or entity that distributes copies of
1252 | the Document to the public.
1253 | 
1254 | A section "Entitled XYZ" means a named subunit of the Document whose
1255 | title either is precisely XYZ or contains XYZ in parentheses following
1256 | text that translates XYZ in another language.  (Here XYZ stands for a
1257 | specific section name mentioned below, such as "Acknowledgements",
1258 | "Dedications", "Endorsements", or "History".)  To "Preserve the Title"
1259 | of such a section when you modify the Document means that it remains a
1260 | section "Entitled XYZ" according to this definition.
1261 | 
1262 | The Document may include Warranty Disclaimers next to the notice which
1263 | states that this License applies to the Document.  These Warranty
1264 | Disclaimers are considered to be included by reference in this
1265 | License, but only as regards disclaiming warranties: any other
1266 | implication that these Warranty Disclaimers may have is void and has
1267 | no effect on the meaning of this License.
1268 | 
1269 | 2. VERBATIM COPYING
1270 | 
1271 | You may copy and distribute the Document in any medium, either
1272 | commercially or noncommercially, provided that this License, the
1273 | copyright notices, and the license notice saying this License applies
1274 | to the Document are reproduced in all copies, and that you add no
1275 | other conditions whatsoever to those of this License.  You may not use
1276 | technical measures to obstruct or control the reading or further
1277 | copying of the copies you make or distribute.  However, you may accept
1278 | compensation in exchange for copies.  If you distribute a large enough
1279 | number of copies you must also follow the conditions in section 3.
1280 | 
1281 | You may also lend copies, under the same conditions stated above, and
1282 | you may publicly display copies.
1283 | 
1284 | 
1285 | 3. COPYING IN QUANTITY
1286 | 
1287 | If you publish printed copies (or copies in media that commonly have
1288 | printed covers) of the Document, numbering more than 100, and the
1289 | Document's license notice requires Cover Texts, you must enclose the
1290 | copies in covers that carry, clearly and legibly, all these Cover
1291 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
1292 | the back cover.  Both covers must also clearly and legibly identify
1293 | you as the publisher of these copies.  The front cover must present
1294 | the full title with all words of the title equally prominent and
1295 | visible.  You may add other material on the covers in addition.
1296 | Copying with changes limited to the covers, as long as they preserve
1297 | the title of the Document and satisfy these conditions, can be treated
1298 | as verbatim copying in other respects.
1299 | 
1300 | If the required texts for either cover are too voluminous to fit
1301 | legibly, you should put the first ones listed (as many as fit
1302 | reasonably) on the actual cover, and continue the rest onto adjacent
1303 | pages.
1304 | 
1305 | If you publish or distribute Opaque copies of the Document numbering
1306 | more than 100, you must either include a machine-readable Transparent
1307 | copy along with each Opaque copy, or state in or with each Opaque copy
1308 | a computer-network location from which the general network-using
1309 | public has access to download using public-standard network protocols
1310 | a complete Transparent copy of the Document, free of added material.
1311 | If you use the latter option, you must take reasonably prudent steps,
1312 | when you begin distribution of Opaque copies in quantity, to ensure
1313 | that this Transparent copy will remain thus accessible at the stated
1314 | location until at least one year after the last time you distribute an
1315 | Opaque copy (directly or through your agents or retailers) of that
1316 | edition to the public.
1317 | 
1318 | It is requested, but not required, that you contact the authors of the
1319 | Document well before redistributing any large number of copies, to
1320 | give them a chance to provide you with an updated version of the
1321 | Document.
1322 | 
1323 | 
1324 | 4. MODIFICATIONS
1325 | 
1326 | You may copy and distribute a Modified Version of the Document under
1327 | the conditions of sections 2 and 3 above, provided that you release
1328 | the Modified Version under precisely this License, with the Modified
1329 | Version filling the role of the Document, thus licensing distribution
1330 | and modification of the Modified Version to whoever possesses a copy
1331 | of it.  In addition, you must do these things in the Modified Version:
1332 | 
1333 | A. Use in the Title Page (and on the covers, if any) a title distinct
1334 |    from that of the Document, and from those of previous versions
1335 |    (which should, if there were any, be listed in the History section
1336 |    of the Document).  You may use the same title as a previous version
1337 |    if the original publisher of that version gives permission.
1338 | B. List on the Title Page, as authors, one or more persons or entities
1339 |    responsible for authorship of the modifications in the Modified
1340 |    Version, together with at least five of the principal authors of the
1341 |    Document (all of its principal authors, if it has fewer than five),
1342 |    unless they release you from this requirement.
1343 | C. State on the Title page the name of the publisher of the
1344 |    Modified Version, as the publisher.
1345 | D. Preserve all the copyright notices of the Document.
1346 | E. Add an appropriate copyright notice for your modifications
1347 |    adjacent to the other copyright notices.
1348 | F. Include, immediately after the copyright notices, a license notice
1349 |    giving the public permission to use the Modified Version under the
1350 |    terms of this License, in the form shown in the Addendum below.
1351 | G. Preserve in that license notice the full lists of Invariant Sections
1352 |    and required Cover Texts given in the Document's license notice.
1353 | H. Include an unaltered copy of this License.
1354 | I. Preserve the section Entitled "History", Preserve its Title, and add
1355 |    to it an item stating at least the title, year, new authors, and
1356 |    publisher of the Modified Version as given on the Title Page.  If
1357 |    there is no section Entitled "History" in the Document, create one
1358 |    stating the title, year, authors, and publisher of the Document as
1359 |    given on its Title Page, then add an item describing the Modified
1360 |    Version as stated in the previous sentence.
1361 | J. Preserve the network location, if any, given in the Document for
1362 |    public access to a Transparent copy of the Document, and likewise
1363 |    the network locations given in the Document for previous versions
1364 |    it was based on.  These may be placed in the "History" section.
1365 |    You may omit a network location for a work that was published at
1366 |    least four years before the Document itself, or if the original
1367 |    publisher of the version it refers to gives permission.
1368 | K. For any section Entitled "Acknowledgements" or "Dedications",
1369 |    Preserve the Title of the section, and preserve in the section all
1370 |    the substance and tone of each of the contributor acknowledgements
1371 |    and/or dedications given therein.
1372 | L. Preserve all the Invariant Sections of the Document,
1373 |    unaltered in their text and in their titles.  Section numbers
1374 |    or the equivalent are not considered part of the section titles.
1375 | M. Delete any section Entitled "Endorsements".  Such a section
1376 |    may not be included in the Modified Version.
1377 | N. Do not retitle any existing section to be Entitled "Endorsements"
1378 |    or to conflict in title with any Invariant Section.
1379 | O. Preserve any Warranty Disclaimers.
1380 | 
1381 | If the Modified Version includes new front-matter sections or
1382 | appendices that qualify as Secondary Sections and contain no material
1383 | copied from the Document, you may at your option designate some or all
1384 | of these sections as invariant.  To do this, add their titles to the
1385 | list of Invariant Sections in the Modified Version's license notice.
1386 | These titles must be distinct from any other section titles.
1387 | 
1388 | You may add a section Entitled "Endorsements", provided it contains
1389 | nothing but endorsements of your Modified Version by various
1390 | parties--for example, statements of peer review or that the text has
1391 | been approved by an organization as the authoritative definition of a
1392 | standard.
1393 | 
1394 | You may add a passage of up to five words as a Front-Cover Text, and a
1395 | passage of up to 25 words as a Back-Cover Text, to the end of the list
1396 | of Cover Texts in the Modified Version.  Only one passage of
1397 | Front-Cover Text and one of Back-Cover Text may be added by (or
1398 | through arrangements made by) any one entity.  If the Document already
1399 | includes a cover text for the same cover, previously added by you or
1400 | by arrangement made by the same entity you are acting on behalf of,
1401 | you may not add another; but you may replace the old one, on explicit
1402 | permission from the previous publisher that added the old one.
1403 | 
1404 | The author(s) and publisher(s) of the Document do not by this License
1405 | give permission to use their names for publicity for or to assert or
1406 | imply endorsement of any Modified Version.
1407 | 
1408 | 
1409 | 5. COMBINING DOCUMENTS
1410 | 
1411 | You may combine the Document with other documents released under this
1412 | License, under the terms defined in section 4 above for modified
1413 | versions, provided that you include in the combination all of the
1414 | Invariant Sections of all of the original documents, unmodified, and
1415 | list them all as Invariant Sections of your combined work in its
1416 | license notice, and that you preserve all their Warranty Disclaimers.
1417 | 
1418 | The combined work need only contain one copy of this License, and
1419 | multiple identical Invariant Sections may be replaced with a single
1420 | copy.  If there are multiple Invariant Sections with the same name but
1421 | different contents, make the title of each such section unique by
1422 | adding at the end of it, in parentheses, the name of the original
1423 | author or publisher of that section if known, or else a unique number.
1424 | Make the same adjustment to the section titles in the list of
1425 | Invariant Sections in the license notice of the combined work.
1426 | 
1427 | In the combination, you must combine any sections Entitled "History"
1428 | in the various original documents, forming one section Entitled
1429 | "History"; likewise combine any sections Entitled "Acknowledgements",
1430 | and any sections Entitled "Dedications".  You must delete all sections
1431 | Entitled "Endorsements".
1432 | 
1433 | 
1434 | 6. COLLECTIONS OF DOCUMENTS
1435 | 
1436 | You may make a collection consisting of the Document and other
1437 | documents released under this License, and replace the individual
1438 | copies of this License in the various documents with a single copy
1439 | that is included in the collection, provided that you follow the rules
1440 | of this License for verbatim copying of each of the documents in all
1441 | other respects.
1442 | 
1443 | You may extract a single document from such a collection, and
1444 | distribute it individually under this License, provided you insert a
1445 | copy of this License into the extracted document, and follow this
1446 | License in all other respects regarding verbatim copying of that
1447 | document.
1448 | 
1449 | 
1450 | 7. AGGREGATION WITH INDEPENDENT WORKS
1451 | 
1452 | A compilation of the Document or its derivatives with other separate
1453 | and independent documents or works, in or on a volume of a storage or
1454 | distribution medium, is called an "aggregate" if the copyright
1455 | resulting from the compilation is not used to limit the legal rights
1456 | of the compilation's users beyond what the individual works permit.
1457 | When the Document is included in an aggregate, this License does not
1458 | apply to the other works in the aggregate which are not themselves
1459 | derivative works of the Document.
1460 | 
1461 | If the Cover Text requirement of section 3 is applicable to these
1462 | copies of the Document, then if the Document is less than one half of
1463 | the entire aggregate, the Document's Cover Texts may be placed on
1464 | covers that bracket the Document within the aggregate, or the
1465 | electronic equivalent of covers if the Document is in electronic form.
1466 | Otherwise they must appear on printed covers that bracket the whole
1467 | aggregate.
1468 | 
1469 | 
1470 | 8. TRANSLATION
1471 | 
1472 | Translation is considered a kind of modification, so you may
1473 | distribute translations of the Document under the terms of section 4.
1474 | Replacing Invariant Sections with translations requires special
1475 | permission from their copyright holders, but you may include
1476 | translations of some or all Invariant Sections in addition to the
1477 | original versions of these Invariant Sections.  You may include a
1478 | translation of this License, and all the license notices in the
1479 | Document, and any Warranty Disclaimers, provided that you also include
1480 | the original English version of this License and the original versions
1481 | of those notices and disclaimers.  In case of a disagreement between
1482 | the translation and the original version of this License or a notice
1483 | or disclaimer, the original version will prevail.
1484 | 
1485 | If a section in the Document is Entitled "Acknowledgements",
1486 | "Dedications", or "History", the requirement (section 4) to Preserve
1487 | its Title (section 1) will typically require changing the actual
1488 | title.
1489 | 
1490 | 
1491 | 9. TERMINATION
1492 | 
1493 | You may not copy, modify, sublicense, or distribute the Document
1494 | except as expressly provided under this License.  Any attempt
1495 | otherwise to copy, modify, sublicense, or distribute it is void, and
1496 | will automatically terminate your rights under this License.
1497 | 
1498 | However, if you cease all violation of this License, then your license
1499 | from a particular copyright holder is reinstated (a) provisionally,
1500 | unless and until the copyright holder explicitly and finally
1501 | terminates your license, and (b) permanently, if the copyright holder
1502 | fails to notify you of the violation by some reasonable means prior to
1503 | 60 days after the cessation.
1504 | 
1505 | Moreover, your license from a particular copyright holder is
1506 | reinstated permanently if the copyright holder notifies you of the
1507 | violation by some reasonable means, this is the first time you have
1508 | received notice of violation of this License (for any work) from that
1509 | copyright holder, and you cure the violation prior to 30 days after
1510 | your receipt of the notice.
1511 | 
1512 | Termination of your rights under this section does not terminate the
1513 | licenses of parties who have received copies or rights from you under
1514 | this License.  If your rights have been terminated and not permanently
1515 | reinstated, receipt of a copy of some or all of the same material does
1516 | not give you any rights to use it.
1517 | 
1518 | 
1519 | 10. FUTURE REVISIONS OF THIS LICENSE
1520 | 
1521 | The Free Software Foundation may publish new, revised versions of the
1522 | GNU Free Documentation License from time to time.  Such new versions
1523 | will be similar in spirit to the present version, but may differ in
1524 | detail to address new problems or concerns.  See
1525 | https://www.gnu.org/licenses/.
1526 | 
1527 | Each version of the License is given a distinguishing version number.
1528 | If the Document specifies that a particular numbered version of this
1529 | License "or any later version" applies to it, you have the option of
1530 | following the terms and conditions either of that specified version or
1531 | of any later version that has been published (not as a draft) by the
1532 | Free Software Foundation.  If the Document does not specify a version
1533 | number of this License, you may choose any version ever published (not
1534 | as a draft) by the Free Software Foundation.  If the Document
1535 | specifies that a proxy can decide which future versions of this
1536 | License can be used, that proxy's public statement of acceptance of a
1537 | version permanently authorizes you to choose that version for the
1538 | Document.
1539 | 
1540 | 11. RELICENSING
1541 | 
1542 | "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
1543 | World Wide Web server that publishes copyrightable works and also
1544 | provides prominent facilities for anybody to edit those works.  A
1545 | public wiki that anybody can edit is an example of such a server.  A
1546 | "Massive Multiauthor Collaboration" (or "MMC") contained in the site
1547 | means any set of copyrightable works thus published on the MMC site.
1548 | 
1549 | "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
1550 | license published by Creative Commons Corporation, a not-for-profit
1551 | corporation with a principal place of business in San Francisco,
1552 | California, as well as future copyleft versions of that license
1553 | published by that same organization.
1554 | 
1555 | "Incorporate" means to publish or republish a Document, in whole or in
1556 | part, as part of another Document.
1557 | 
1558 | An MMC is "eligible for relicensing" if it is licensed under this
1559 | License, and if all works that were first published under this License
1560 | somewhere other than this MMC, and subsequently incorporated in whole or
1561 | in part into the MMC, (1) had no cover texts or invariant sections, and
1562 | (2) were thus incorporated prior to November 1, 2008.
1563 | 
1564 | The operator of an MMC Site may republish an MMC contained in the site
1565 | under CC-BY-SA on the same site at any time before August 1, 2009,
1566 | provided the MMC is eligible for relicensing.
1567 | 
1568 | 
1569 | ADDENDUM: How to use this License for your documents
1570 | 
1571 | To use this License in a document you have written, include a copy of
1572 | the License in the document and put the following copyright and
1573 | license notices just after the title page:
1574 | 
1575 |     Copyright (c)  YEAR  YOUR NAME.
1576 |     Permission is granted to copy, distribute and/or modify this document
1577 |     under the terms of the GNU Free Documentation License, Version 1.3
1578 |     or any later version published by the Free Software Foundation;
1579 |     with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
1580 |     A copy of the license is included in the section entitled "GNU
1581 |     Free Documentation License".
1582 | 
1583 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
1584 | replace the "with...Texts." line with this:
1585 | 
1586 |     with the Invariant Sections being LIST THEIR TITLES, with the
1587 |     Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
1588 | 
1589 | If you have Invariant Sections without Cover Texts, or some other
1590 | combination of the three, merge those two alternatives to suit the
1591 | situation.
1592 | 
1593 | If your document contains nontrivial examples of program code, we
1594 | recommend releasing these examples in parallel under your choice of
1595 | free software license, such as the GNU General Public License,
1596 | to permit their use in free software.
1597 |
1598 | #+end_export 1599 | 1600 | #+html: 1626 | -------------------------------------------------------------------------------- /doclicense.texi: -------------------------------------------------------------------------------- 1 | @c The GNU Free Documentation License. 2 | @center Version 1.3, 3 November 2008 3 | 4 | @c This file is intended to be included within another document, 5 | @c hence no sectioning command or @node. 6 | 7 | @display 8 | Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 9 | @uref{https://fsf.org/} 10 | 11 | Everyone is permitted to copy and distribute verbatim copies 12 | of this license document, but changing it is not allowed. 13 | @end display 14 | 15 | @enumerate 0 16 | @item 17 | PREAMBLE 18 | 19 | The purpose of this License is to make a manual, textbook, or other 20 | functional and useful document @dfn{free} in the sense of freedom: to 21 | assure everyone the effective freedom to copy and redistribute it, 22 | with or without modifying it, either commercially or noncommercially. 23 | Secondarily, this License preserves for the author and publisher a way 24 | to get credit for their work, while not being considered responsible 25 | for modifications made by others. 26 | 27 | This License is a kind of ``copyleft'', which means that derivative 28 | works of the document must themselves be free in the same sense. It 29 | complements the GNU General Public License, which is a copyleft 30 | license designed for free software. 31 | 32 | We have designed this License in order to use it for manuals for free 33 | software, because free software needs free documentation: a free 34 | program should come with manuals providing the same freedoms that the 35 | software does. But this License is not limited to software manuals; 36 | it can be used for any textual work, regardless of subject matter or 37 | whether it is published as a printed book. We recommend this License 38 | principally for works whose purpose is instruction or reference. 39 | 40 | @item 41 | APPLICABILITY AND DEFINITIONS 42 | 43 | This License applies to any manual or other work, in any medium, that 44 | contains a notice placed by the copyright holder saying it can be 45 | distributed under the terms of this License. Such a notice grants a 46 | world-wide, royalty-free license, unlimited in duration, to use that 47 | work under the conditions stated herein. The ``Document'', below, 48 | refers to any such manual or work. Any member of the public is a 49 | licensee, and is addressed as ``you''. You accept the license if you 50 | copy, modify or distribute the work in a way requiring permission 51 | under copyright law. 52 | 53 | A ``Modified Version'' of the Document means any work containing the 54 | Document or a portion of it, either copied verbatim, or with 55 | modifications and/or translated into another language. 56 | 57 | A ``Secondary Section'' is a named appendix or a front-matter section 58 | of the Document that deals exclusively with the relationship of the 59 | publishers or authors of the Document to the Document's overall 60 | subject (or to related matters) and contains nothing that could fall 61 | directly within that overall subject. (Thus, if the Document is in 62 | part a textbook of mathematics, a Secondary Section may not explain 63 | any mathematics.) The relationship could be a matter of historical 64 | connection with the subject or with related matters, or of legal, 65 | commercial, philosophical, ethical or political position regarding 66 | them. 67 | 68 | The ``Invariant Sections'' are certain Secondary Sections whose titles 69 | are designated, as being those of Invariant Sections, in the notice 70 | that says that the Document is released under this License. If a 71 | section does not fit the above definition of Secondary then it is not 72 | allowed to be designated as Invariant. The Document may contain zero 73 | Invariant Sections. If the Document does not identify any Invariant 74 | Sections then there are none. 75 | 76 | The ``Cover Texts'' are certain short passages of text that are listed, 77 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that 78 | the Document is released under this License. A Front-Cover Text may 79 | be at most 5 words, and a Back-Cover Text may be at most 25 words. 80 | 81 | A ``Transparent'' copy of the Document means a machine-readable copy, 82 | represented in a format whose specification is available to the 83 | general public, that is suitable for revising the document 84 | straightforwardly with generic text editors or (for images composed of 85 | pixels) generic paint programs or (for drawings) some widely available 86 | drawing editor, and that is suitable for input to text formatters or 87 | for automatic translation to a variety of formats suitable for input 88 | to text formatters. A copy made in an otherwise Transparent file 89 | format whose markup, or absence of markup, has been arranged to thwart 90 | or discourage subsequent modification by readers is not Transparent. 91 | An image format is not Transparent if used for any substantial amount 92 | of text. A copy that is not ``Transparent'' is called ``Opaque''. 93 | 94 | Examples of suitable formats for Transparent copies include plain 95 | ASCII without markup, Texinfo input format, La@TeX{} input 96 | format, SGML or XML using a publicly available 97 | DTD, and standard-conforming simple HTML, 98 | PostScript or PDF designed for human modification. Examples 99 | of transparent image formats include PNG, XCF and 100 | JPG@. Opaque formats include proprietary formats that can be 101 | read and edited only by proprietary word processors, SGML or 102 | XML for which the DTD and/or processing tools are 103 | not generally available, and the machine-generated HTML, 104 | PostScript or PDF produced by some word processors for 105 | output purposes only. 106 | 107 | The ``Title Page'' means, for a printed book, the title page itself, 108 | plus such following pages as are needed to hold, legibly, the material 109 | this License requires to appear in the title page. For works in 110 | formats which do not have any title page as such, ``Title Page'' means 111 | the text near the most prominent appearance of the work's title, 112 | preceding the beginning of the body of the text. 113 | 114 | The ``publisher'' means any person or entity that distributes copies 115 | of the Document to the public. 116 | 117 | A section ``Entitled XYZ'' means a named subunit of the Document whose 118 | title either is precisely XYZ or contains XYZ in parentheses following 119 | text that translates XYZ in another language. (Here XYZ stands for a 120 | specific section name mentioned below, such as ``Acknowledgements'', 121 | ``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' 122 | of such a section when you modify the Document means that it remains a 123 | section ``Entitled XYZ'' according to this definition. 124 | 125 | The Document may include Warranty Disclaimers next to the notice which 126 | states that this License applies to the Document. These Warranty 127 | Disclaimers are considered to be included by reference in this 128 | License, but only as regards disclaiming warranties: any other 129 | implication that these Warranty Disclaimers may have is void and has 130 | no effect on the meaning of this License. 131 | 132 | @item 133 | VERBATIM COPYING 134 | 135 | You may copy and distribute the Document in any medium, either 136 | commercially or noncommercially, provided that this License, the 137 | copyright notices, and the license notice saying this License applies 138 | to the Document are reproduced in all copies, and that you add no other 139 | conditions whatsoever to those of this License. You may not use 140 | technical measures to obstruct or control the reading or further 141 | copying of the copies you make or distribute. However, you may accept 142 | compensation in exchange for copies. If you distribute a large enough 143 | number of copies you must also follow the conditions in section 3. 144 | 145 | You may also lend copies, under the same conditions stated above, and 146 | you may publicly display copies. 147 | 148 | @item 149 | COPYING IN QUANTITY 150 | 151 | If you publish printed copies (or copies in media that commonly have 152 | printed covers) of the Document, numbering more than 100, and the 153 | Document's license notice requires Cover Texts, you must enclose the 154 | copies in covers that carry, clearly and legibly, all these Cover 155 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 156 | the back cover. Both covers must also clearly and legibly identify 157 | you as the publisher of these copies. The front cover must present 158 | the full title with all words of the title equally prominent and 159 | visible. You may add other material on the covers in addition. 160 | Copying with changes limited to the covers, as long as they preserve 161 | the title of the Document and satisfy these conditions, can be treated 162 | as verbatim copying in other respects. 163 | 164 | If the required texts for either cover are too voluminous to fit 165 | legibly, you should put the first ones listed (as many as fit 166 | reasonably) on the actual cover, and continue the rest onto adjacent 167 | pages. 168 | 169 | If you publish or distribute Opaque copies of the Document numbering 170 | more than 100, you must either include a machine-readable Transparent 171 | copy along with each Opaque copy, or state in or with each Opaque copy 172 | a computer-network location from which the general network-using 173 | public has access to download using public-standard network protocols 174 | a complete Transparent copy of the Document, free of added material. 175 | If you use the latter option, you must take reasonably prudent steps, 176 | when you begin distribution of Opaque copies in quantity, to ensure 177 | that this Transparent copy will remain thus accessible at the stated 178 | location until at least one year after the last time you distribute an 179 | Opaque copy (directly or through your agents or retailers) of that 180 | edition to the public. 181 | 182 | It is requested, but not required, that you contact the authors of the 183 | Document well before redistributing any large number of copies, to give 184 | them a chance to provide you with an updated version of the Document. 185 | 186 | @item 187 | MODIFICATIONS 188 | 189 | You may copy and distribute a Modified Version of the Document under 190 | the conditions of sections 2 and 3 above, provided that you release 191 | the Modified Version under precisely this License, with the Modified 192 | Version filling the role of the Document, thus licensing distribution 193 | and modification of the Modified Version to whoever possesses a copy 194 | of it. In addition, you must do these things in the Modified Version: 195 | 196 | @enumerate A 197 | @item 198 | Use in the Title Page (and on the covers, if any) a title distinct 199 | from that of the Document, and from those of previous versions 200 | (which should, if there were any, be listed in the History section 201 | of the Document). You may use the same title as a previous version 202 | if the original publisher of that version gives permission. 203 | 204 | @item 205 | List on the Title Page, as authors, one or more persons or entities 206 | responsible for authorship of the modifications in the Modified 207 | Version, together with at least five of the principal authors of the 208 | Document (all of its principal authors, if it has fewer than five), 209 | unless they release you from this requirement. 210 | 211 | @item 212 | State on the Title page the name of the publisher of the 213 | Modified Version, as the publisher. 214 | 215 | @item 216 | Preserve all the copyright notices of the Document. 217 | 218 | @item 219 | Add an appropriate copyright notice for your modifications 220 | adjacent to the other copyright notices. 221 | 222 | @item 223 | Include, immediately after the copyright notices, a license notice 224 | giving the public permission to use the Modified Version under the 225 | terms of this License, in the form shown in the Addendum below. 226 | 227 | @item 228 | Preserve in that license notice the full lists of Invariant Sections 229 | and required Cover Texts given in the Document's license notice. 230 | 231 | @item 232 | Include an unaltered copy of this License. 233 | 234 | @item 235 | Preserve the section Entitled ``History'', Preserve its Title, and add 236 | to it an item stating at least the title, year, new authors, and 237 | publisher of the Modified Version as given on the Title Page. If 238 | there is no section Entitled ``History'' in the Document, create one 239 | stating the title, year, authors, and publisher of the Document as 240 | given on its Title Page, then add an item describing the Modified 241 | Version as stated in the previous sentence. 242 | 243 | @item 244 | Preserve the network location, if any, given in the Document for 245 | public access to a Transparent copy of the Document, and likewise 246 | the network locations given in the Document for previous versions 247 | it was based on. These may be placed in the ``History'' section. 248 | You may omit a network location for a work that was published at 249 | least four years before the Document itself, or if the original 250 | publisher of the version it refers to gives permission. 251 | 252 | @item 253 | For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve 254 | the Title of the section, and preserve in the section all the 255 | substance and tone of each of the contributor acknowledgements and/or 256 | dedications given therein. 257 | 258 | @item 259 | Preserve all the Invariant Sections of the Document, 260 | unaltered in their text and in their titles. Section numbers 261 | or the equivalent are not considered part of the section titles. 262 | 263 | @item 264 | Delete any section Entitled ``Endorsements''. Such a section 265 | may not be included in the Modified Version. 266 | 267 | @item 268 | Do not retitle any existing section to be Entitled ``Endorsements'' or 269 | to conflict in title with any Invariant Section. 270 | 271 | @item 272 | Preserve any Warranty Disclaimers. 273 | @end enumerate 274 | 275 | If the Modified Version includes new front-matter sections or 276 | appendices that qualify as Secondary Sections and contain no material 277 | copied from the Document, you may at your option designate some or all 278 | of these sections as invariant. To do this, add their titles to the 279 | list of Invariant Sections in the Modified Version's license notice. 280 | These titles must be distinct from any other section titles. 281 | 282 | You may add a section Entitled ``Endorsements'', provided it contains 283 | nothing but endorsements of your Modified Version by various 284 | parties---for example, statements of peer review or that the text has 285 | been approved by an organization as the authoritative definition of a 286 | standard. 287 | 288 | You may add a passage of up to five words as a Front-Cover Text, and a 289 | passage of up to 25 words as a Back-Cover Text, to the end of the list 290 | of Cover Texts in the Modified Version. Only one passage of 291 | Front-Cover Text and one of Back-Cover Text may be added by (or 292 | through arrangements made by) any one entity. If the Document already 293 | includes a cover text for the same cover, previously added by you or 294 | by arrangement made by the same entity you are acting on behalf of, 295 | you may not add another; but you may replace the old one, on explicit 296 | permission from the previous publisher that added the old one. 297 | 298 | The author(s) and publisher(s) of the Document do not by this License 299 | give permission to use their names for publicity for or to assert or 300 | imply endorsement of any Modified Version. 301 | 302 | @item 303 | COMBINING DOCUMENTS 304 | 305 | You may combine the Document with other documents released under this 306 | License, under the terms defined in section 4 above for modified 307 | versions, provided that you include in the combination all of the 308 | Invariant Sections of all of the original documents, unmodified, and 309 | list them all as Invariant Sections of your combined work in its 310 | license notice, and that you preserve all their Warranty Disclaimers. 311 | 312 | The combined work need only contain one copy of this License, and 313 | multiple identical Invariant Sections may be replaced with a single 314 | copy. If there are multiple Invariant Sections with the same name but 315 | different contents, make the title of each such section unique by 316 | adding at the end of it, in parentheses, the name of the original 317 | author or publisher of that section if known, or else a unique number. 318 | Make the same adjustment to the section titles in the list of 319 | Invariant Sections in the license notice of the combined work. 320 | 321 | In the combination, you must combine any sections Entitled ``History'' 322 | in the various original documents, forming one section Entitled 323 | ``History''; likewise combine any sections Entitled ``Acknowledgements'', 324 | and any sections Entitled ``Dedications''. You must delete all 325 | sections Entitled ``Endorsements.'' 326 | 327 | @item 328 | COLLECTIONS OF DOCUMENTS 329 | 330 | You may make a collection consisting of the Document and other documents 331 | released under this License, and replace the individual copies of this 332 | License in the various documents with a single copy that is included in 333 | the collection, provided that you follow the rules of this License for 334 | verbatim copying of each of the documents in all other respects. 335 | 336 | You may extract a single document from such a collection, and distribute 337 | it individually under this License, provided you insert a copy of this 338 | License into the extracted document, and follow this License in all 339 | other respects regarding verbatim copying of that document. 340 | 341 | @item 342 | AGGREGATION WITH INDEPENDENT WORKS 343 | 344 | A compilation of the Document or its derivatives with other separate 345 | and independent documents or works, in or on a volume of a storage or 346 | distribution medium, is called an ``aggregate'' if the copyright 347 | resulting from the compilation is not used to limit the legal rights 348 | of the compilation's users beyond what the individual works permit. 349 | When the Document is included in an aggregate, this License does not 350 | apply to the other works in the aggregate which are not themselves 351 | derivative works of the Document. 352 | 353 | If the Cover Text requirement of section 3 is applicable to these 354 | copies of the Document, then if the Document is less than one half of 355 | the entire aggregate, the Document's Cover Texts may be placed on 356 | covers that bracket the Document within the aggregate, or the 357 | electronic equivalent of covers if the Document is in electronic form. 358 | Otherwise they must appear on printed covers that bracket the whole 359 | aggregate. 360 | 361 | @item 362 | TRANSLATION 363 | 364 | Translation is considered a kind of modification, so you may 365 | distribute translations of the Document under the terms of section 4. 366 | Replacing Invariant Sections with translations requires special 367 | permission from their copyright holders, but you may include 368 | translations of some or all Invariant Sections in addition to the 369 | original versions of these Invariant Sections. You may include a 370 | translation of this License, and all the license notices in the 371 | Document, and any Warranty Disclaimers, provided that you also include 372 | the original English version of this License and the original versions 373 | of those notices and disclaimers. In case of a disagreement between 374 | the translation and the original version of this License or a notice 375 | or disclaimer, the original version will prevail. 376 | 377 | If a section in the Document is Entitled ``Acknowledgements'', 378 | ``Dedications'', or ``History'', the requirement (section 4) to Preserve 379 | its Title (section 1) will typically require changing the actual 380 | title. 381 | 382 | @item 383 | TERMINATION 384 | 385 | You may not copy, modify, sublicense, or distribute the Document 386 | except as expressly provided under this License. Any attempt 387 | otherwise to copy, modify, sublicense, or distribute it is void, and 388 | will automatically terminate your rights under this License. 389 | 390 | However, if you cease all violation of this License, then your license 391 | from a particular copyright holder is reinstated (a) provisionally, 392 | unless and until the copyright holder explicitly and finally 393 | terminates your license, and (b) permanently, if the copyright holder 394 | fails to notify you of the violation by some reasonable means prior to 395 | 60 days after the cessation. 396 | 397 | Moreover, your license from a particular copyright holder is 398 | reinstated permanently if the copyright holder notifies you of the 399 | violation by some reasonable means, this is the first time you have 400 | received notice of violation of this License (for any work) from that 401 | copyright holder, and you cure the violation prior to 30 days after 402 | your receipt of the notice. 403 | 404 | Termination of your rights under this section does not terminate the 405 | licenses of parties who have received copies or rights from you under 406 | this License. If your rights have been terminated and not permanently 407 | reinstated, receipt of a copy of some or all of the same material does 408 | not give you any rights to use it. 409 | 410 | @item 411 | FUTURE REVISIONS OF THIS LICENSE 412 | 413 | The Free Software Foundation may publish new, revised versions 414 | of the GNU Free Documentation License from time to time. Such new 415 | versions will be similar in spirit to the present version, but may 416 | differ in detail to address new problems or concerns. See 417 | @uref{https://www.gnu.org/licenses/}. 418 | 419 | Each version of the License is given a distinguishing version number. 420 | If the Document specifies that a particular numbered version of this 421 | License ``or any later version'' applies to it, you have the option of 422 | following the terms and conditions either of that specified version or 423 | of any later version that has been published (not as a draft) by the 424 | Free Software Foundation. If the Document does not specify a version 425 | number of this License, you may choose any version ever published (not 426 | as a draft) by the Free Software Foundation. If the Document 427 | specifies that a proxy can decide which future versions of this 428 | License can be used, that proxy's public statement of acceptance of a 429 | version permanently authorizes you to choose that version for the 430 | Document. 431 | 432 | @item 433 | RELICENSING 434 | 435 | ``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any 436 | World Wide Web server that publishes copyrightable works and also 437 | provides prominent facilities for anybody to edit those works. A 438 | public wiki that anybody can edit is an example of such a server. A 439 | ``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the 440 | site means any set of copyrightable works thus published on the MMC 441 | site. 442 | 443 | ``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 444 | license published by Creative Commons Corporation, a not-for-profit 445 | corporation with a principal place of business in San Francisco, 446 | California, as well as future copyleft versions of that license 447 | published by that same organization. 448 | 449 | ``Incorporate'' means to publish or republish a Document, in whole or 450 | in part, as part of another Document. 451 | 452 | An MMC is ``eligible for relicensing'' if it is licensed under this 453 | License, and if all works that were first published under this License 454 | somewhere other than this MMC, and subsequently incorporated in whole 455 | or in part into the MMC, (1) had no cover texts or invariant sections, 456 | and (2) were thus incorporated prior to November 1, 2008. 457 | 458 | The operator of an MMC Site may republish an MMC contained in the site 459 | under CC-BY-SA on the same site at any time before August 1, 2009, 460 | provided the MMC is eligible for relicensing. 461 | 462 | @end enumerate 463 | 464 | @page 465 | @heading ADDENDUM: How to use this License for your documents 466 | 467 | To use this License in a document you have written, include a copy of 468 | the License in the document and put the following copyright and 469 | license notices just after the title page: 470 | 471 | @smallexample 472 | @group 473 | Copyright (C) @var{year} @var{your name}. 474 | Permission is granted to copy, distribute and/or modify this document 475 | under the terms of the GNU Free Documentation License, Version 1.3 476 | or any later version published by the Free Software Foundation; 477 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 478 | Texts. A copy of the license is included in the section entitled ``GNU 479 | Free Documentation License''. 480 | @end group 481 | @end smallexample 482 | 483 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 484 | replace the ``with@dots{}Texts.''@: line with this: 485 | 486 | @smallexample 487 | @group 488 | with the Invariant Sections being @var{list their titles}, with 489 | the Front-Cover Texts being @var{list}, and with the Back-Cover Texts 490 | being @var{list}. 491 | @end group 492 | @end smallexample 493 | 494 | If you have Invariant Sections without Cover Texts, or some other 495 | combination of the three, merge those two alternatives to suit the 496 | situation. 497 | 498 | If your document contains nontrivial examples of program code, we 499 | recommend releasing these examples in parallel under your choice of 500 | free software license, such as the GNU General Public License, 501 | to permit their use in free software. 502 | 503 | @c Local Variables: 504 | @c ispell-local-pdict: "ispell-dict" 505 | @c End: 506 | -------------------------------------------------------------------------------- /mct.el: -------------------------------------------------------------------------------- 1 | ;;; mct.el --- Minibuffer Confines Transcended -*- lexical-binding: t -*- 2 | 3 | ;; Copyright (C) 2021-2024 Free Software Foundation, Inc. 4 | 5 | ;; Author: Protesilaos Stavrou 6 | ;; Maintainer: Protesilaos Stavrou 7 | ;; URL: https://github.com/protesilaos/mct 8 | ;; Version: 1.0.0 9 | ;; Package-Requires: ((emacs "29.1")) 10 | 11 | ;; This file is NOT part of GNU Emacs. 12 | 13 | ;; This program is free software; you can redistribute it and/or modify 14 | ;; it under the terms of the GNU General Public License as published by 15 | ;; the Free Software Foundation, either version 3 of the License, or (at 16 | ;; your option) any later version. 17 | ;; 18 | ;; This program is distributed in the hope that it will be useful, 19 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 20 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 21 | ;; GNU General Public License for more details. 22 | ;; 23 | ;; You should have received a copy of the GNU General Public License 24 | ;; along with this program. If not, see . 25 | 26 | ;;; Commentary: 27 | ;; 28 | ;; Enhancements for the default minibuffer completion UI of Emacs. In 29 | ;; essence, MCT is (i) a very thin layer of interactivity on top of the 30 | ;; out-of-the-box completion experience, and (ii) glue code that combines 31 | ;; built-in functionalities to make the default completion framework work 32 | ;; like that of more featureful third-party options. 33 | 34 | ;;; Code: 35 | 36 | ;;;; General utilities 37 | 38 | (defgroup mct () 39 | "Minibuffer Confines Transcended. 40 | A layer of interactivity that integrates the standard minibuffer 41 | and the Completions." 42 | :group 'minibuffer) 43 | 44 | (make-obsolete 'mct-completion-windows-regexp 'mct--completions-window-name "0.5.0") 45 | 46 | (defcustom mct-completion-window-size (cons #'mct-frame-height-third 1) 47 | "Set the maximum and minimum height of the Completions buffer. 48 | 49 | The value is a cons cell in the form of (max-height . min-height) 50 | where each value is either a natural number or a function which 51 | returns such a number. 52 | 53 | The default maximum height of the window is calculated by the 54 | function `mct-frame-height-third', which finds the closest round 55 | number to 1/3 of the frame's height. While the default minimum 56 | height is 1. This means that during live completions the 57 | Completions window will shrink or grow to show candidates within 58 | the specified boundaries. To disable this bouncing effect, set 59 | both max-height and min-height to the same number. 60 | 61 | If nil, do not try to fit the Completions buffer to its window. 62 | 63 | Also see `mct-live-completion'." 64 | :type '(choice (const :tag "Disable size constraints" nil) 65 | (cons 66 | (choice (function :tag "Function to determine maximum height") 67 | (natnum :tag "Maximum height in number of lines")) 68 | (choice (function :tag "Function to determine minimum height") 69 | (natnum :tag "Minimum height in number of lines")))) 70 | :group 'mct) 71 | 72 | (defcustom mct-remove-shadowed-file-names nil 73 | "Delete shadowed parts of file names from the minibuffer. 74 | 75 | For example, if the user types ~/ after a long path name, 76 | everything preceding the ~/ is removed so the interactive 77 | selection process starts again from the user's $HOME. 78 | 79 | Only works when `file-name-shadow-mode' is enabled" 80 | :type 'boolean 81 | :group 'mct) 82 | 83 | (defcustom mct-hide-completion-mode-line nil 84 | "When non-nil, hide the Completions buffer mode line." 85 | :type 'boolean 86 | :group 'mct) 87 | 88 | (make-obsolete 'mct-apply-completion-stripes nil "1.0.0") 89 | 90 | (defcustom mct-live-completion t 91 | "Control auto-display and live-update of Completions buffer. 92 | 93 | When nil, the user has to manually request completions, using the 94 | regular activating commands. The Completions buffer is never 95 | updated live to match user input. Updating has to be handled 96 | manually. This is like the out-of-the-box minibuffer completion 97 | experience. 98 | 99 | When set to the value `visible', the Completions buffer is live 100 | updated only if it is visible. The actual display of the 101 | completions is still handled manually. For this reason, the 102 | `visible' style does not read the `mct-minimum-input', meaning 103 | that it will always try to live update the visible completions, 104 | regardless of input length. 105 | 106 | When non-nil (the default), the Completions buffer is 107 | automatically displayed once the `mct-minimum-input' is met and 108 | is hidden if the input drops below that threshold. While 109 | visible, the buffer is updated live to match the user's input. 110 | 111 | Note that every command or completion category in the 112 | `mct-completion-passlist' ignores this option altogether. This 113 | means that every such symbol will always show the Completions 114 | buffer automatically and will always update its contents live. 115 | Same principle for `mct-completion-blocklist', which will always 116 | disable both the automatic display and live updating of the 117 | Completions buffer. 118 | 119 | Also see `mct-completion-window-size'." 120 | :type '(choice 121 | (const :tag "Disable live-updating" nil) 122 | (const :tag "Enable live-updating" t) 123 | (const :tag "Live update only visible Completions" visible)) 124 | :group 'mct) 125 | 126 | (defcustom mct-minimum-input 3 127 | "Live update completions when input is >= N. 128 | 129 | Setting this to a value greater than 1 can help reduce the total 130 | number of candidates that are being computed." 131 | :type 'natnum 132 | :group 'mct) 133 | 134 | (defcustom mct-completing-read-multiple-indicator t 135 | "When non-nil show an indicator for `completing-read-multiple' prompts. 136 | If nil, do not show anything. Those prompts will look like the generic ones. 137 | 138 | The indicator informs the user this is a `completing-read-multiple' 139 | prompt and also shows the `crm-separator', which is usually a comma." 140 | :type 'boolean 141 | :package-version '(mct . "1.1.0") 142 | :group 'mct) 143 | 144 | (defcustom mct-live-update-delay 0.3 145 | "Delay in seconds before updating the Completions buffer. 146 | Set this to 0 to disable the delay. 147 | 148 | This applies in all cases covered by `mct-live-completion'." 149 | :type 'number 150 | :group 'mct) 151 | 152 | (defcustom mct-completion-blocklist nil 153 | "List of symbols where live completions are outright disabled. 154 | 155 | The value of this user option is a list of symbols. Those can 156 | refer to commands like `find-file' or completion categories such 157 | as `file', `buffer', or what other packages define like Consult's 158 | `consult-location' category. 159 | 160 | This means that they ignore `mct-live-completion'. They do not 161 | automatically display the Completions buffer, nor do they update 162 | it to match user input. 163 | 164 | The Completions buffer can still be accessed with commands that 165 | place it in a window (such as `mct-list-completions-toggle', 166 | `mct-switch-to-completions-top'). 167 | 168 | When the `mct-completion-blocklist' and the `mct-completion-passlist' 169 | are in conflict, the former takes precedence. 170 | 171 | Perhaps a less drastic measure is to set `mct-minimum-input' to 172 | an appropriate value. Or better use `mct-completion-passlist'. 173 | 174 | Read the manual for known completion categories." 175 | :type '(repeat symbol) 176 | :group 'mct) 177 | 178 | (defcustom mct-completion-passlist nil 179 | "List of symbols where live completions are always enabled. 180 | 181 | The value of this user option is a list of symbols. Those can 182 | refer to commands like `find-file' or completion categories such 183 | as `file', `buffer', or what other packages define like Consult's 184 | `consult-location' category. 185 | 186 | This means that they ignore the value of `mct-live-completion' 187 | and the `mct-minimum-input'. They also bypass any possible delay 188 | introduced by `mct-live-update-delay'. 189 | 190 | When the `mct-completion-blocklist' and the `mct-completion-passlist' 191 | are in conflict, the former takes precedence. 192 | 193 | Read the manual for known completion categories." 194 | :type '(repeat symbol) 195 | :group 'mct) 196 | 197 | (make-obsolete-variable 'mct-display-buffer-action nil "1.0.0") 198 | (make-obsolete-variable 'mct-completions-format nil "1.0.0") 199 | (make-obsolete-variable 'mct-persist-dynamic-completion 'mct-completion-passlist "1.1.0") 200 | 201 | ;;;; Completion metadata 202 | 203 | (defun mct--this-command () 204 | "Return this command." 205 | (or (bound-and-true-p current-minibuffer-command) this-command)) 206 | 207 | (defun mct--completion-category () 208 | "Return completion category." 209 | (when-let* ((window (active-minibuffer-window))) 210 | (with-current-buffer (window-buffer window) 211 | (completion-metadata-get 212 | (completion-metadata (buffer-substring-no-properties 213 | (minibuffer-prompt-end) 214 | (max (minibuffer-prompt-end) (point))) 215 | minibuffer-completion-table 216 | minibuffer-completion-predicate) 217 | 'category)))) 218 | 219 | (defun mct--symbol-in-list (list) 220 | "Test if command or category is in LIST." 221 | (or (memq (mct--this-command) list) 222 | (memq (mct--completion-category) list))) 223 | 224 | (defun mct--passlist-p () 225 | "Return non-nil if symbol is in the `mct-completion-passlist'." 226 | (mct--symbol-in-list mct-completion-passlist)) 227 | 228 | (defun mct--blocklist-p () 229 | "Return non-nil if symbol is in the `mct-completion-blocklist'." 230 | (mct--symbol-in-list mct-completion-blocklist)) 231 | 232 | ;;;; Sorting functions for `completions-sort' (Emacs 29) 233 | 234 | (defvar mct-sort-alpha-function #'string-version-lessp 235 | "Function to perform alphabetic sorting between two strings.") 236 | 237 | (defun mct-sort-by-alpha (completions) 238 | "Sort COMPLETIONS alphabetically. 239 | This function can be used as the value of the user option 240 | `completions-sort'." 241 | (sort 242 | completions 243 | (lambda (string1 string2) 244 | (funcall mct-sort-alpha-function string1 string2)))) 245 | 246 | (defun mct-sort-by-alpha-length (completions) 247 | "Sort COMPLETIONS first alphabetically, then by length. 248 | This function can be used as the value of the user option 249 | `completions-sort'." 250 | (sort 251 | completions 252 | (lambda (string1 string2) 253 | (or (funcall mct-sort-alpha-function string1 string2) 254 | (< (length string1) (length string2)))))) 255 | 256 | ;; Based on `minibuffer-sort-by-history' from Emacs 30. 257 | (defun mct-sort-by-history (completions) 258 | "Sort COMPLETIONS by minibuffer history, else return them unsorted. 259 | This function can be used as the value of the user option 260 | `completions-sort'." 261 | (let ((alphabetized (mct-sort-by-alpha completions))) 262 | ;; Only use history when it's specific to these completions. 263 | (if (eq minibuffer-history-variable 264 | (default-value minibuffer-history-variable)) 265 | alphabetized 266 | (minibuffer--sort-by-position 267 | (minibuffer--sort-preprocess-history minibuffer-completion-base) 268 | alphabetized)))) 269 | 270 | (defun mct-sort-directories-then-files (completions) 271 | "Sort COMPLETIONS with `mct-sort-by-alpha-length' with directories first." 272 | (setq completions (mct-sort-by-alpha completions)) 273 | ;; But then move directories first 274 | (nconc (seq-filter (lambda (x) (string-suffix-p "/" x)) completions) 275 | (seq-remove (lambda (x) (string-suffix-p "/" x)) completions))) 276 | 277 | (defun mct-sort-multi-category (completions) 278 | "Sort COMPLETIONS per completion category. 279 | This function can be used as the value of the user option 280 | `completions-sort'." 281 | (pcase (mct--completion-category) 282 | ('kill-ring completions) ; no sorting 283 | ('file (mct-sort-directories-then-files completions)) 284 | (_ (mct-sort-by-history completions)))) 285 | 286 | ;;;; Basics of intersection between minibuffer and Completions buffer 287 | 288 | (defface mct-highlight-candidate 289 | '((t :inherit highlight :extend nil)) 290 | "Face for current candidate in the Completions buffer." 291 | :group 'mct) 292 | 293 | (defun mct--first-line-completion-p () 294 | "Return non-nil if first line has completion candidates." 295 | (eq (line-number-at-pos (point-min)) 296 | (line-number-at-pos (mct--first-completion-point)))) 297 | 298 | ;; Thanks to Omar Antolín Camarena for recommending the use of 299 | ;; `cursor-sensor-functions' and the concomitant hook with 300 | ;; `cursor-sensor-mode' instead of the dirty hacks I had before to 301 | ;; prevent the cursor from moving to that position where no completion 302 | ;; candidates could be found at point (e.g. it would break `embark-act' 303 | ;; as it could not read the topmost candidate when point was at the 304 | ;; beginning of the line, unless the point was moved forward). 305 | (defun mct--setup-clean-completions () 306 | "Keep only completion candidates in the Completions." 307 | (unless completions-header-format 308 | (with-current-buffer standard-output 309 | (unless (mct--first-line-completion-p) 310 | (goto-char (point-min)) 311 | (let ((inhibit-read-only t)) 312 | (delete-region (line-beginning-position) (1+ (line-end-position))) 313 | (insert (propertize " " 314 | 'cursor-sensor-functions 315 | (list 316 | (lambda (_win prev dir) 317 | (when (eq dir 'entered) 318 | (goto-char prev)))))) 319 | (put-text-property (point-min) (point) 'invisible t)))))) 320 | 321 | (defun mct-frame-height-third () 322 | "Return round number of 1/3 of `frame-height'. 323 | Can be used in `mct-completion-window-size'." 324 | (floor (frame-height) 3)) 325 | 326 | (define-obsolete-function-alias 327 | 'mct--frame-height-fraction 328 | 'mct-frame-height-third 329 | "1.0.0") 330 | 331 | (defun mct--height (param) 332 | "Return height of PARAM in number of lines." 333 | (cond 334 | ((natnump param) param) 335 | ((functionp param) (funcall param)) 336 | ;; There is no compelling reason to fall back to 5. It just feels 337 | ;; like a reasonable small value... 338 | (t 5))) 339 | 340 | (defun mct--fit-completions-window (&rest _args) 341 | "Fit Completions buffer to its window." 342 | (when-let* ((window (mct--get-completion-window)) 343 | (size mct-completion-window-size) 344 | (max-height (mct--height (car size))) 345 | (min-height (mct--height (cdr size))) 346 | ;; For vertical alignment of contents and horizontal 347 | ;; borders of completion window when content size do 348 | ;; not reaches the upper bound of the window height. 349 | (window-resize-pixelwise t) 350 | 351 | ;; `fit-window-to-buffer' calculates the an upper 352 | ;; bound of window height as the minimum of provided 353 | ;; `max-height' and the sum of the content size and 354 | ;; some pixels border lines, which results in the 355 | ;; final window height lacking for some pixels when 356 | ;; the content size larger than `max-height'. So we 357 | ;; need some tricks to align contents and window 358 | ;; horizontal borders for this case. The following 359 | ;; few lines calculate the amount of lacked pixels, 360 | ;; `delta-px', and enlarge window height if in the 361 | ;; case. 362 | 363 | (frame (window-frame window)) 364 | (line-height-px (window-default-line-height window)) 365 | ;; `max-height' in pixels 366 | (max-height-px (* line-height-px (mct--height max-height))) 367 | ;; Current window height, including all the stuffs. 368 | (height-px (+ (cdr (window-text-pixel-size 369 | window nil t nil (frame-pixel-height frame) t)) 370 | (window-scroll-bar-height window) 371 | (window-bottom-divider-width window))) 372 | (mode-line-height-px (window-mode-line-height window)) 373 | (delta-px (% mode-line-height-px line-height-px))) ; Offset 374 | (fit-window-to-buffer window max-height min-height) 375 | (when (< max-height-px height-px) 376 | (window-resize window delta-px nil window window-resize-pixelwise)))) 377 | 378 | (defun mct--minimum-input () 379 | "Test for minimum requisite input for live completions. 380 | See `mct-minimum-input'." 381 | (>= (- (point-max) (minibuffer-prompt-end)) mct-minimum-input)) 382 | 383 | ;;;;; Live-updating Completions buffer 384 | 385 | (defvar mct--completions-window-name "\\`\\*Completions.*\\*\\'" 386 | "Regexp to match window names with completion candidates.") 387 | 388 | ;; Adapted from Omar Antolín Camarena's live-completions library: 389 | ;; . 390 | (defun mct--live-completions-refresh-immediately () 391 | "Update the *Completions* buffer immediately." 392 | (when (minibufferp) ; skip if we've exited already 393 | (while-no-input 394 | (if (or (mct--minimum-input) 395 | (eq mct-live-completion 'visible)) 396 | (condition-case nil 397 | (save-match-data 398 | (save-excursion 399 | (goto-char (point-max)) 400 | (mct--show-completions))) 401 | (quit (abort-recursive-edit))) 402 | (minibuffer-hide-completions))))) 403 | 404 | (defvar mct--timer nil 405 | "Latest timer object for live completions.") 406 | 407 | (defun mct--live-completions-refresh (&rest _) 408 | "Update the *Completions* buffer with a delay. 409 | Meant to be added to `after-change-functions'." 410 | (when (and 411 | ;; Check that live completions are enabled by looking at 412 | ;; `after-change-functions'. This check is needed for 413 | ;; Consult integration, which refreshes the display 414 | ;; asynchronously. 415 | (memq #'mct--live-completions-refresh after-change-functions) 416 | ;; Update only visible completion windows? 417 | (or (not (eq mct-live-completion 'visible)) 418 | (window-live-p (mct--get-completion-window)))) 419 | (when mct--timer 420 | (cancel-timer mct--timer) 421 | (setq mct--timer nil)) 422 | (if (> mct-live-update-delay 0) 423 | (setq mct--timer (run-with-idle-timer 424 | mct-live-update-delay 425 | nil #'mct--live-completions-refresh-immediately)) 426 | (mct--live-completions-refresh-immediately)))) 427 | 428 | (defun mct--setup-live-completions () 429 | "Set up the Completions buffer." 430 | (cond 431 | ((or (null mct-live-completion) (mct--blocklist-p))) 432 | ;; ;; NOTE 2022-02-25: The passlist setup we had here was being 433 | ;; ;; called too early in `mct--completing-read-advice'. It would 434 | ;; ;; fail to filter out the current candidate from the list 435 | ;; ;; (e.g. current buffer from `switch-to-buffer'). This would, in 436 | ;; ;; turn, hinder the scrolling behaviour of `minibuffer-complete'. 437 | ;; ;; See: . The 438 | ;; ;; replacement function is `mct--setup-passlist' which is hooked 439 | ;; ;; directly to `minibuffer-setup-hook'. 440 | ;; 441 | ;; ((mct--passlist-p) 442 | ;; (setq-local mct-minimum-input 0) 443 | ;; (setq-local mct-live-update-delay 0) 444 | ;; (mct--show-completions) 445 | ;; (add-hook 'after-change-functions #'mct--live-completions-refresh nil t)) 446 | ((not (mct--blocklist-p)) 447 | (add-hook 'after-change-functions #'mct--live-completions-refresh nil t)))) 448 | 449 | (defun mct--setup-passlist () 450 | "Set up the minibuffer for `mct-completion-passlist'." 451 | (when (and (mct--passlist-p) (mct--minibuffer-p) (not (mct--blocklist-p))) 452 | (setq-local mct-minimum-input 0) 453 | (setq-local mct-live-update-delay 0) 454 | (mct--show-completions))) 455 | 456 | (defvar-local mct--active nil 457 | "Minibuffer local variable, t if Mct is active.") 458 | 459 | (defun mct--minibuffer-p () 460 | "Return t if Mct is active." 461 | (when-let* ((win (active-minibuffer-window)) 462 | (buf (window-buffer win))) 463 | (buffer-local-value 'mct--active buf))) 464 | 465 | (defun mct--minibuffer-completion-help-advice (&rest app) 466 | "Prepare APP advice around `display-completion-list'." 467 | (if (mct--minibuffer-p) 468 | (let ((completions-format 'one-column)) 469 | (apply app) 470 | (mct--fit-completions-window)) 471 | (apply app))) 472 | 473 | (defun mct--completing-read-advice (&rest app) 474 | "Prepare advice around `completing-read-default'. 475 | Apply APP by first setting up the minibuffer to work with Mct." 476 | (minibuffer-with-setup-hook 477 | (lambda () 478 | (setq-local resize-mini-windows t 479 | completion-auto-help t) 480 | (setq mct--active t) 481 | (mct--setup-live-completions) 482 | (mct--setup-minibuffer-keymap) 483 | (mct--setup-shadow-files)) 484 | (apply app))) 485 | 486 | ;;;; Commands and helper functions 487 | 488 | (declare-function text-property-search-backward "text-property-search" (property &optional value predicate not-current)) 489 | (declare-function text-property-search-forward "text-property-search" (property &optional value predicate not-current)) 490 | (declare-function prop-match-beginning "text-property-search" (cl-x)) 491 | (declare-function prop-match-end "text-property-search" (cl-x)) 492 | 493 | ;;;;; Focus minibuffer and/or show completions 494 | 495 | ;;;###autoload 496 | (defun mct-focus-minibuffer () 497 | "Focus the active minibuffer." 498 | (interactive nil mct-mode) 499 | (when-let* ((mini (active-minibuffer-window))) 500 | (select-window mini))) 501 | 502 | (defun mct--get-completion-window () 503 | "Find a live window showing completion candidates." 504 | (get-window-with-predicate 505 | (lambda (window) 506 | (string-match-p 507 | mct--completions-window-name 508 | (buffer-name (window-buffer window)))))) 509 | 510 | (defun mct--show-completions () 511 | "Show the Completions buffer." 512 | (let (;; don't ring the bell in `minibuffer-completion-help' 513 | ;; when <= 1 completion exists. 514 | (ring-bell-function #'ignore) 515 | (message-log-max nil) 516 | (inhibit-message t)) 517 | (minibuffer-completion-help))) 518 | 519 | ;;;###autoload 520 | (defun mct-focus-mini-or-completions () 521 | "Focus the active minibuffer or the Completions window. 522 | 523 | If both the minibuffer and the Completions are present, this 524 | command will first move per invocation to the former, then the 525 | latter, and then continue to switch between the two. 526 | 527 | The continuous switch is essentially the same as running 528 | `mct-focus-minibuffer' and `switch-to-Completions in 529 | succession. 530 | 531 | What constitutes a Completions window is ultimately determined 532 | by `mct--completions-window-name'." 533 | (interactive nil mct-mode) 534 | (let* ((mini (active-minibuffer-window)) 535 | (completions (mct--get-completion-window))) 536 | (cond 537 | ((and mini (not (minibufferp))) 538 | (select-window mini nil)) 539 | ((and completions (not (eq (selected-window) completions))) 540 | (select-window completions nil))))) 541 | 542 | ;;;###autoload 543 | (defun mct-list-completions-toggle () 544 | "Toggle the presentation of the Completions buffer." 545 | (interactive nil mct-mode) 546 | (if (mct--get-completion-window) 547 | (minibuffer-hide-completions) 548 | (mct--show-completions))) 549 | 550 | ;;;;; Cyclic motions between minibuffer and Completions buffer 551 | 552 | (defun mct--completion-at-point-p () 553 | "Return non-nil if there is a completion at point." 554 | (get-text-property (point) 'completion--string)) 555 | 556 | (defun mct--arg-completion-point-p (arg) 557 | "Return non-nil if ARGth next completion exists." 558 | (save-excursion 559 | (next-completion arg) 560 | (mct--completion-at-point-p))) 561 | 562 | (defun mct--first-completion-point () 563 | "Return the `point' of the first completion." 564 | (save-excursion 565 | (goto-char (point-max)) 566 | (when completions-header-format 567 | (next-completion 1)) 568 | (point))) 569 | 570 | (defun mct--last-completion-point () 571 | "Return the `point' of the last completion." 572 | (save-excursion 573 | (goto-char (point-max)) 574 | (next-completion -1) 575 | (point))) 576 | 577 | (defun mct--completions-no-completion-line-p (arg) 578 | "Check if ARGth line has a completion candidate." 579 | (save-excursion 580 | (vertical-motion arg) 581 | (null (mct--completion-at-point-p)))) 582 | 583 | (defun mct--switch-to-completions () 584 | "Subroutine for switching to the Completions buffer." 585 | (unless (mct--get-completion-window) 586 | (mct--show-completions)) 587 | (switch-to-completions)) 588 | 589 | (defun mct-switch-to-completions-top () 590 | "Switch to the top of the Completions buffer." 591 | (interactive nil mct-mode) 592 | (mct--switch-to-completions) 593 | (goto-char (mct--first-completion-point))) 594 | 595 | (defun mct-switch-to-completions-bottom () 596 | "Switch to the bottom of the Completions buffer." 597 | (interactive nil mct-mode) 598 | (mct--switch-to-completions) 599 | (goto-char (point-max)) 600 | (next-completion -1) 601 | (goto-char (line-beginning-position)) 602 | (unless (mct--completion-at-point-p) 603 | (next-completion 1)) 604 | (recenter 605 | (- -1 606 | (min (max 0 scroll-margin) 607 | (truncate (/ (window-body-height) 4.0)))) 608 | t)) 609 | 610 | (defun mct--empty-line-p (arg) 611 | "Return non-nil if ARGth line is empty." 612 | (unless (mct--arg-completion-point-p arg) 613 | (save-excursion 614 | (goto-char (line-beginning-position)) 615 | (and (not (bobp)) 616 | (or (beginning-of-line (1+ arg)) t) 617 | (save-match-data 618 | (looking-at "[\s\t]*$")))))) 619 | 620 | (defun mct--bottom-of-completions-p (arg) 621 | "Test if point is at the notional bottom of the Completions. 622 | ARG is a numeric argument for `next-completion', as described in 623 | `mct-next-completion-or-mini'." 624 | (or (eobp) 625 | (= (save-excursion (next-completion arg) (point)) (point-max)) 626 | (= (save-excursion (forward-line arg) (point)) (point-max)) 627 | ;; The empty final line case which should avoid candidates with 628 | ;; spaces or line breaks... 629 | (mct--empty-line-p arg))) 630 | 631 | (defun mct-next-completion-or-mini (&optional arg) 632 | "Move to the next completion or switch to the minibuffer. 633 | This performs a regular motion for optional ARG candidates, but 634 | when point can no longer move in that direction it switches to 635 | the minibuffer." 636 | (interactive "p" mct-mode) 637 | (let ((count (or arg 1))) 638 | (if (mct--bottom-of-completions-p count) 639 | (mct-focus-minibuffer) 640 | (next-completion count)))) 641 | 642 | (defun mct--motion-below-point-min-p (arg) 643 | "Return non-nil if backward ARG motion exceeds `point-min'." 644 | (let ((line (- (line-number-at-pos) arg))) 645 | (or (< line 1) 646 | (when completions-header-format 647 | (= (save-excursion 648 | (previous-completion arg) 649 | (line-number-at-pos)) 650 | (line-number-at-pos (point-max))))))) 651 | 652 | (defun mct--top-of-completions-p (arg) 653 | "Test if point is at the notional top of the Completions. 654 | ARG is a numeric argument for `previous-completion', as described in 655 | `mct-previous-completion-or-mini'." 656 | (or (bobp) 657 | (mct--motion-below-point-min-p arg) 658 | ;; FIXME 2021-12-27: Why do we need this now? Regression upstream? 659 | (eq (line-number-at-pos) 1))) 660 | 661 | (defun mct-previous-completion-or-mini (&optional arg) 662 | "Move to the previous completion or switch to the minibuffer. 663 | This performs a regular motion for optional ARG candidates, but 664 | when point can no longer move in that direction it switches to 665 | the minibuffer." 666 | (interactive "p" mct-mode) 667 | (let ((count (if (natnump arg) arg 1))) 668 | (if (mct--top-of-completions-p count) 669 | (mct-focus-minibuffer) 670 | (previous-completion count)))) 671 | 672 | (defun mct-next-completion-group (&optional arg) 673 | "Move to the next completion group. 674 | If ARG is supplied, move that many completion groups at a time." 675 | (interactive "p" mct-mode) 676 | (dotimes (_ (or arg 1)) 677 | (when-let* ((group (save-excursion (text-property-search-forward 'face 'completions-group-separator t nil)))) 678 | (let ((pos (prop-match-end group))) 679 | (unless (eq pos (point-max)) 680 | (goto-char pos) 681 | (next-completion 1)))))) 682 | 683 | (defun mct-previous-completion-group (&optional arg) 684 | "Move to the previous completion group. 685 | If ARG is supplied, move that many completion groups at a time." 686 | (interactive "p" mct-mode) 687 | (dotimes (_ (or arg 1)) 688 | ;; skip back, so if we're at the top of a group, we go to the previous one... 689 | (forward-line -1) 690 | (if-let* ((group (save-excursion (text-property-search-backward 'face 'completions-group-separator t nil)))) 691 | (let ((pos (prop-match-beginning group))) 692 | (unless (eq pos (point-min)) 693 | (goto-char pos) 694 | (next-completion 1))) 695 | ;; ...and if there was a match, go back down, so the point doesn't 696 | ;; end in the group separator 697 | (forward-line 1)))) 698 | 699 | ;;;;; Candidate selection 700 | 701 | ;; The difference between this and choose-completion is that it will 702 | ;; exit even if a directory is selected in find-file, whereas 703 | ;; choose-completion expands the directory and continues the session. 704 | (defun mct-choose-completion-exit () 705 | "Run `choose-completion' in the Completions buffer and exit." 706 | (interactive nil mct-mode) 707 | (choose-completion) 708 | (when (active-minibuffer-window) 709 | (exit-minibuffer))) 710 | 711 | (defun mct-choose-completion-no-exit () 712 | "Run `choose-completion' in the Completions without exiting." 713 | (interactive nil mct-mode) 714 | (let ((completion-no-auto-exit t)) 715 | (choose-completion))) 716 | 717 | (defvar crm-completion-table) 718 | (defvar crm-separator) 719 | 720 | ;; This is adapted from the README of the `vertico' package by Daniel 721 | ;; Mendler. 722 | (defun mct--crm-indicator (args) 723 | "Display an indicator for `completing-read-multiple' based on ARGS." 724 | (cons (format "%s %s | %s" 725 | (propertize "`completing-read-multiple' separator is" 'face 'shadow) 726 | (propertize 727 | (format " %s " 728 | (replace-regexp-in-string 729 | "\\`\\[.*?]\\*\\|\\[.*?]\\*\\'" "" 730 | crm-separator)) 731 | 'face '(highlight bold)) 732 | (car args)) 733 | (cdr args))) 734 | 735 | (defun mct--regex-to-separator (regex) 736 | "Parse REGEX of `crm-separator' in `mct-choose-completion-dwim'." 737 | (save-match-data 738 | (cond 739 | ;; whitespace-delimited, like default & org-set-tag-command 740 | ((string-match (rx 741 | bos "[" (1+ blank) "]*" 742 | (group (1+ any)) 743 | "[" (1+ blank) "]*" eos) 744 | regex) 745 | (match-string 1 regex)) 746 | ;; literal character 747 | ((string= regex (regexp-quote regex)) 748 | regex)))) 749 | 750 | (defun mct-choose-completion-dwim () 751 | "Append to minibuffer when at `completing-read-multiple' prompt. 752 | In any other prompt use `mct-choose-completion-no-exit'." 753 | (interactive nil mct-mode) 754 | (when-let* ((mini (active-minibuffer-window)) 755 | (window (mct--get-completion-window)) 756 | (buffer (window-buffer window))) 757 | (mct-choose-completion-no-exit) 758 | (with-current-buffer (window-buffer mini) 759 | (when crm-completion-table 760 | (let ((separator (or (mct--regex-to-separator crm-separator) 761 | ","))) 762 | (insert separator)) 763 | (let ((inhibit-message t)) 764 | (switch-to-completions)))))) 765 | 766 | (defun mct-edit-completion () 767 | "Edit the current completion candidate inside the minibuffer. 768 | 769 | The current candidate is the one at point while inside the 770 | Completions buffer. 771 | 772 | When point is in the minibuffer, the current candidate is 773 | determined as follows: 774 | 775 | + The one at the last known position in the Completions 776 | window (if the window is deleted and produced again, this value 777 | is reset). 778 | 779 | + The first candidate in the Completions buffer. 780 | 781 | A candidate is recognised for as long as point is not past its 782 | last character." 783 | (interactive nil mct-mode) 784 | (when-let* ((window (mct--get-completion-window)) 785 | ((active-minibuffer-window))) 786 | (with-current-buffer (window-buffer window) 787 | (let* ((old-point (save-excursion 788 | (select-window window) 789 | (window-old-point))) 790 | (pos (if (= old-point (point-min)) 791 | (mct--first-completion-point) 792 | old-point))) 793 | (goto-char pos) 794 | (mct-choose-completion-no-exit))))) 795 | 796 | (defun mct-complete-and-exit () 797 | "Complete current input and exit. 798 | 799 | This has the same effect as with 800 | \\\\[mct-edit-completion], 801 | followed by exiting the minibuffer with that candidate." 802 | (interactive nil mct-mode) 803 | (mct-edit-completion) 804 | (exit-minibuffer)) 805 | 806 | ;;;;; Miscellaneous commands 807 | 808 | ;; This is needed to circumvent `mct--setup-clean-Completions with regard to 809 | ;; `cursor-sensor-functions'. 810 | (defun mct-beginning-of-buffer () 811 | "Go to the top of the Completions buffer." 812 | (interactive nil mct-mode) 813 | (goto-char (mct--first-completion-point))) 814 | 815 | (defun mct-keyboard-quit-dwim () 816 | "Control the exit behaviour for Completions buffers. 817 | 818 | If in a Completions buffer and unless the region is active, run 819 | `abort-recursive-edit'. Otherwise run `keyboard-quit'. 820 | 821 | If the region is active, deactivate it. A second invocation of 822 | this command is then required to abort the session." 823 | (interactive nil mct-mode) 824 | (when (derived-mode-p 'completion-list-mode) 825 | (cond 826 | ((null (active-minibuffer-window)) 827 | (minibuffer-hide-completions)) 828 | ((use-region-p) (keyboard-quit)) 829 | (t (abort-recursive-edit))))) 830 | 831 | ;;;; Global minor mode setup 832 | 833 | ;;;;; Stylistic tweaks and refinements 834 | 835 | ;; Note that this solves bug#45686: 836 | ;; 837 | ;; TODO review that stealthily does not affect the region mode, it seems intrusive. 838 | (defun mct--stealthily (&rest app) 839 | "Prevent minibuffer default from counting as a modification. 840 | Apply APP while inhibiting modification hooks." 841 | (let ((inhibit-modification-hooks t)) 842 | (apply app))) 843 | 844 | (defun mct--setup-appearance () 845 | "Set up variables for the appearance of the Completions buffer." 846 | (when mct-hide-completion-mode-line 847 | (setq-local mode-line-format nil)) 848 | (when completions-header-format 849 | (setq-local display-line-numbers-offset -1))) 850 | 851 | ;;;;; Shadowed path 852 | 853 | ;; Adapted from icomplete.el 854 | (defun mct--shadow-filenames (&rest _) 855 | "Hide shadowed file names." 856 | (let ((saved-point (point))) 857 | (when (and 858 | mct-remove-shadowed-file-names 859 | (eq (mct--completion-category) 'file) 860 | rfn-eshadow-overlay (overlay-buffer rfn-eshadow-overlay) 861 | (eq (mct--this-command) 'self-insert-command) 862 | (= saved-point (point-max)) 863 | (or (>= (- (point) (overlay-end rfn-eshadow-overlay)) 2) 864 | (eq ?/ (char-before (- (point) 2))))) 865 | (delete-region (overlay-start rfn-eshadow-overlay) 866 | (overlay-end rfn-eshadow-overlay))))) 867 | 868 | (defun mct--setup-shadow-files () 869 | "Set up shadowed file name deletion." 870 | (add-hook 'after-change-functions #'mct--shadow-filenames nil t)) 871 | 872 | ;;;;; Highlight current candidate 873 | 874 | (defvar-local mct--highlight-overlay nil 875 | "Overlay to highlight candidate in the Completions buffer.") 876 | 877 | (defvar mct--overlay-priority -50 878 | "Priority used on the `mct--highlight-overlay'. 879 | This value means that it is overriden by the active region.") 880 | 881 | ;; The `if-let*' is to prevent highlighting of empty space, such as by 882 | ;; clicking on it with the mouse. 883 | (defun mct--completions-completion-beg () 884 | "Return point of completion candidate at START and END." 885 | (if-let* ((string (mct--completion-at-point-p))) 886 | (save-excursion 887 | (prop-match-beginning (text-property-search-forward 'completion--string))) 888 | (point))) 889 | 890 | ;; Same as above for the `if-let*'. 891 | (defun mct--completions-completion-end () 892 | "Return end of completion candidate." 893 | (if-let* ((string (mct--completion-at-point-p))) 894 | (save-excursion 895 | (1+ (line-end-position))) 896 | (point))) 897 | 898 | (defun mct--overlay-make () 899 | "Make overlay to highlight current candidate." 900 | (let ((ol (make-overlay (point) (point)))) 901 | (overlay-put ol 'priority mct--overlay-priority) 902 | (overlay-put ol 'face 'mct-highlight-candidate) 903 | ol)) 904 | 905 | (defun mct--overlay-move (overlay) 906 | "Highlight the candidate at point with OVERLAY." 907 | (let* ((beg (mct--completions-completion-beg)) 908 | (end (mct--completions-completion-end))) 909 | (move-overlay overlay beg end))) 910 | 911 | (defun mct--completions-candidate-highlight () 912 | "Activate `mct--highlight-overlay'." 913 | (unless (overlayp mct--highlight-overlay) 914 | (setq mct--highlight-overlay (mct--overlay-make))) 915 | (mct--overlay-move mct--highlight-overlay)) 916 | 917 | (defun mct--setup-highlighting () 918 | "Highlight the current completion in the Completions buffer." 919 | (add-hook 'post-command-hook #'mct--completions-candidate-highlight nil t)) 920 | 921 | ;;;;; Keymaps 922 | 923 | (defvar mct-minibuffer-completion-list-map 924 | (let ((map (make-sparse-keymap))) 925 | (define-key map [remap keyboard-quit] #'mct-keyboard-quit-dwim) 926 | (define-key map [remap next-line] #'mct-next-completion-or-mini) 927 | (define-key map (kbd "n") #'mct-next-completion-or-mini) 928 | (define-key map (kbd "") #'mct-next-completion-or-mini) 929 | (define-key map [remap previous-line] #'mct-previous-completion-or-mini) 930 | (define-key map (kbd "p") #'mct-previous-completion-or-mini) 931 | (define-key map (kbd "") #'mct-previous-completion-or-mini) 932 | (define-key map [remap backward-paragraph] #'mct-previous-completion-group) 933 | (define-key map [remap forward-paragraph] #'mct-next-completion-group) 934 | (define-key map (kbd "M-p") #'mct-previous-completion-group) 935 | (define-key map (kbd "M-n") #'mct-next-completion-group) 936 | (define-key map (kbd "e") #'mct-focus-minibuffer) 937 | (define-key map (kbd "M-e") #'mct-edit-completion) 938 | (define-key map (kbd "TAB") #'mct-choose-completion-no-exit) 939 | (define-key map (kbd "RET") #'mct-choose-completion-exit) 940 | (define-key map (kbd "M-RET") #'mct-choose-completion-dwim) 941 | (define-key map [remap beginning-of-buffer] #'mct-beginning-of-buffer) 942 | map) 943 | "Derivative of `completion-list-mode-map'.") 944 | 945 | (defvar mct-minibuffer-local-completion-map 946 | (let ((map (make-sparse-keymap))) 947 | (define-key map (kbd "C-j") #'exit-minibuffer) 948 | (define-key map [remap next-line] #'mct-switch-to-completions-top) 949 | (define-key map [remap next-line-or-history-element] #'mct-switch-to-completions-top) 950 | (define-key map (kbd "") #'mct-switch-to-completions-top) 951 | (define-key map [remap previous-line] #'mct-switch-to-completions-bottom) 952 | (define-key map (kbd "") #'mct-switch-to-completions-bottom) 953 | (define-key map (kbd "M-e") #'mct-edit-completion) 954 | (define-key map (kbd "C-") #'mct-complete-and-exit) 955 | (define-key map (kbd "C-l") #'mct-list-completions-toggle) 956 | (define-key map (kbd "") nil) 957 | (define-key map (kbd "") nil) 958 | map) 959 | "Derivative of `minibuffer-local-completion-map'.") 960 | 961 | (defun mct--setup-completion-list-keymap () 962 | "Set up completion list keymap." 963 | (use-local-map 964 | (make-composed-keymap mct-minibuffer-completion-list-map 965 | (current-local-map)))) 966 | 967 | (defun mct--setup-minibuffer-keymap () 968 | "Set up minibuffer keymap." 969 | (use-local-map 970 | (make-composed-keymap mct-minibuffer-local-completion-map 971 | (current-local-map)))) 972 | 973 | (defun mct--setup-completion-list () 974 | "Set up the completion-list for Mct." 975 | (when (mct--minibuffer-p) 976 | (setq-local completion-show-help nil 977 | completion-wrap-movement nil ; Emacs 29 978 | completions-highlight-face nil 979 | truncate-lines t) 980 | (mct--setup-clean-completions) 981 | (mct--setup-appearance) 982 | (mct--setup-completion-list-keymap) 983 | (mct--setup-highlighting) 984 | (cursor-sensor-mode))) 985 | 986 | ;;;;; Dynamic completion 987 | 988 | (defun mct-persist-completions-buffer (&rest _) 989 | "Persist the completions buffer if there are still candidates. 990 | Do this under any of the following conditions: 991 | 992 | - The command is in the `mct-completion-passlist'. 993 | 994 | - The `mct-live-completion' is non-nil." 995 | (when (and (not (mct--blocklist-p)) 996 | (or (mct--passlist-p) mct-live-completion)) 997 | (mct-focus-minibuffer) 998 | (mct--show-completions))) 999 | 1000 | (defun mct--setup-persistent-completions () 1001 | "Set up `mct-persist-completions-buffer'." 1002 | (let ((commands '(choose-completion minibuffer-complete minibuffer-force-complete))) 1003 | (if (bound-and-true-p mct-mode) 1004 | (dolist (fn commands) 1005 | (advice-add fn :after #'mct-persist-completions-buffer)) 1006 | (dolist (fn commands) 1007 | (advice-remove fn #'mct-persist-completions-buffer))))) 1008 | 1009 | ;;;;; mct-mode declaration 1010 | 1011 | (declare-function minibuf-eldef-setup-minibuffer "minibuf-eldef") 1012 | 1013 | ;;;###autoload 1014 | (define-minor-mode mct-mode 1015 | "Set up opinionated default completion UI." 1016 | :global t 1017 | :group 'mct 1018 | (if mct-mode 1019 | (progn 1020 | (add-hook 'completion-list-mode-hook #'mct--setup-completion-list) 1021 | (add-hook 'minibuffer-setup-hook #'mct--setup-passlist) 1022 | (advice-add #'completing-read-default :around #'mct--completing-read-advice) 1023 | (advice-add #'completing-read-multiple :around #'mct--completing-read-advice) 1024 | (when mct-completing-read-multiple-indicator 1025 | (advice-add #'completing-read-multiple :filter-args #'mct--crm-indicator)) 1026 | (advice-add #'minibuffer-completion-help :around #'mct--minibuffer-completion-help-advice) 1027 | (advice-add #'minibuf-eldef-setup-minibuffer :around #'mct--stealthily)) 1028 | (remove-hook 'completion-list-mode-hook #'mct--setup-completion-list) 1029 | (remove-hook 'minibuffer-setup-hook #'mct--setup-passlist) 1030 | (advice-remove #'completing-read-default #'mct--completing-read-advice) 1031 | (advice-remove #'completing-read-multiple #'mct--completing-read-advice) 1032 | (advice-remove #'completing-read-multiple #'mct--crm-indicator) 1033 | (advice-remove #'minibuffer-completion-help #'mct--minibuffer-completion-help-advice) 1034 | (advice-remove #'minibuf-eldef-setup-minibuffer #'mct--stealthily)) 1035 | (mct--setup-persistent-completions) 1036 | (mct--setup-message-advices)) 1037 | 1038 | (define-obsolete-function-alias 1039 | 'mct-minibuffer-mode 1040 | 'mct-mode 1041 | "1.0.0") 1042 | 1043 | (make-obsolete 'mct-region-mode nil "1.0.0") 1044 | 1045 | ;; Adapted from Omar Antolín Camarena's live-completions library: 1046 | ;; . 1047 | (defun mct--honor-inhibit-message (&rest app) 1048 | "Honor variable `inhibit-message' while applying APP." 1049 | (unless (and (mct--minibuffer-p) inhibit-message) 1050 | (apply app))) 1051 | 1052 | ;; Thanks to Omar Antolín Camarena for providing the messageless and 1053 | ;; stealthily. Source: . 1054 | (defun mct--messageless (&rest app) 1055 | "Set `minibuffer-message-timeout' to 0 while applying APP." 1056 | (if (mct--minibuffer-p) 1057 | (let ((minibuffer-message-timeout 0)) 1058 | (apply app)) 1059 | (apply app))) 1060 | 1061 | (defun mct--setup-message-advices () 1062 | "Silence the minibuffer and the Completions." 1063 | (if mct-mode 1064 | (progn 1065 | (dolist (fn '(exit-minibuffer 1066 | choose-completion 1067 | minibuffer-force-complete 1068 | minibuffer-complete-and-exit 1069 | minibuffer-force-complete-and-exit)) 1070 | (advice-add fn :around #'mct--messageless)) 1071 | (advice-add #'minibuffer-message :around #'mct--honor-inhibit-message)) 1072 | (dolist (fn '(exit-minibuffer 1073 | choose-completion 1074 | minibuffer-force-complete 1075 | minibuffer-complete-and-exit 1076 | minibuffer-force-complete-and-exit)) 1077 | (advice-remove fn #'mct--messageless)) 1078 | (advice-remove #'minibuffer-message #'mct--honor-inhibit-message))) 1079 | 1080 | (provide 'mct) 1081 | ;;; mct.el ends here 1082 | --------------------------------------------------------------------------------