| 1 | ;;; icomplete.el --- minibuffer completion incremental feedback |
| 2 | |
| 3 | ;; Copyright (C) 1992-1994, 1997, 1999, 2001-2012 |
| 4 | ;; Free Software Foundation, Inc. |
| 5 | |
| 6 | ;; Author: Ken Manheimer <klm@i.am> |
| 7 | ;; Maintainer: Ken Manheimer <klm@i.am> |
| 8 | ;; Created: Mar 1993 Ken Manheimer, klm@nist.gov - first release to usenet |
| 9 | ;; Last update: Ken Manheimer <klm@i.am>, 11/18/1999. |
| 10 | ;; Keywords: help, abbrev |
| 11 | |
| 12 | ;; This file is part of GNU Emacs. |
| 13 | |
| 14 | ;; GNU Emacs is free software: you can redistribute it and/or modify |
| 15 | ;; it under the terms of the GNU General Public License as published by |
| 16 | ;; the Free Software Foundation, either version 3 of the License, or |
| 17 | ;; (at your option) any later version. |
| 18 | |
| 19 | ;; GNU Emacs is distributed in the hope that it will be useful, |
| 20 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 21 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 22 | ;; GNU General Public License for more details. |
| 23 | |
| 24 | ;; You should have received a copy of the GNU General Public License |
| 25 | ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |
| 26 | |
| 27 | ;;; Commentary: |
| 28 | |
| 29 | ;; Loading this package implements a more fine-grained minibuffer |
| 30 | ;; completion feedback scheme. Prospective completions are concisely |
| 31 | ;; indicated within the minibuffer itself, with each successive |
| 32 | ;; keystroke. |
| 33 | |
| 34 | ;; See `icomplete-completions' docstring for a description of the |
| 35 | ;; icomplete display format. |
| 36 | |
| 37 | ;; See the `icomplete-minibuffer-setup-hook' docstring for a means to |
| 38 | ;; customize icomplete setup for interoperation with other |
| 39 | ;; minibuffer-oriented packages. |
| 40 | |
| 41 | ;; To activate icomplete mode, load the package and use the |
| 42 | ;; `icomplete-mode' function. You can subsequently deactivate it by |
| 43 | ;; invoking the function icomplete-mode with a negative prefix-arg |
| 44 | ;; (C-U -1 ESC-x icomplete-mode). Also, you can prevent activation of |
| 45 | ;; the mode during package load by first setting the variable |
| 46 | ;; `icomplete-mode' to nil. Icompletion can be enabled any time after |
| 47 | ;; the package is loaded by invoking icomplete-mode without a prefix |
| 48 | ;; arg. |
| 49 | |
| 50 | ;; Thanks to everyone for their suggestions for refinements of this |
| 51 | ;; package. I particularly have to credit Michael Cook, who |
| 52 | ;; implemented an incremental completion style in his 'iswitch' |
| 53 | ;; functions that served as a model for icomplete. Some other |
| 54 | ;; contributors: Noah Friedman (restructuring as minor mode), Colin |
| 55 | ;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and others. |
| 56 | |
| 57 | ;; klm. |
| 58 | |
| 59 | ;;; Code: |
| 60 | |
| 61 | ;;;_* Provide |
| 62 | (provide 'icomplete) |
| 63 | |
| 64 | |
| 65 | (defgroup icomplete nil |
| 66 | "Show completions dynamically in minibuffer." |
| 67 | :prefix "icomplete-" |
| 68 | :group 'minibuffer) |
| 69 | |
| 70 | (defvar icomplete-prospects-length 80) |
| 71 | (make-obsolete-variable |
| 72 | 'icomplete-prospects-length 'icomplete-prospects-height "23.1") |
| 73 | |
| 74 | (defcustom icomplete-separator " | " |
| 75 | "String used by icomplete to separate alternatives in the minibuffer." |
| 76 | :type 'string |
| 77 | :version "24.3") |
| 78 | |
| 79 | ;;;_* User Customization variables |
| 80 | (defcustom icomplete-prospects-height |
| 81 | ;; 20 is an estimated common size for the prompt + minibuffer content, to |
| 82 | ;; try to guess the number of lines used up by icomplete-prospects-length. |
| 83 | (+ 1 (/ (+ icomplete-prospects-length 20) (window-width))) |
| 84 | "Maximum number of lines to use in the minibuffer." |
| 85 | :type 'integer |
| 86 | :group 'icomplete |
| 87 | :version "23.1") |
| 88 | |
| 89 | (defcustom icomplete-compute-delay .3 |
| 90 | "Completions-computation stall, used only with large-number completions. |
| 91 | See `icomplete-delay-completions-threshold'." |
| 92 | :type 'number |
| 93 | :group 'icomplete) |
| 94 | |
| 95 | (defcustom icomplete-delay-completions-threshold 400 |
| 96 | "Pending-completions number over which to apply `icomplete-compute-delay'." |
| 97 | :type 'integer |
| 98 | :group 'icomplete) |
| 99 | |
| 100 | (defcustom icomplete-max-delay-chars 3 |
| 101 | "Maximum number of initial chars to apply icomplete compute delay." |
| 102 | :type 'integer |
| 103 | :group 'icomplete) |
| 104 | |
| 105 | (defcustom icomplete-minibuffer-setup-hook nil |
| 106 | "Icomplete-specific customization of minibuffer setup. |
| 107 | |
| 108 | This hook is run during minibuffer setup if icomplete is active. |
| 109 | It is intended for use in customizing icomplete for interoperation |
| 110 | with other features and packages. For instance: |
| 111 | |
| 112 | \(add-hook 'icomplete-minibuffer-setup-hook |
| 113 | \(function |
| 114 | \(lambda () |
| 115 | \(make-local-variable 'max-mini-window-height) |
| 116 | \(setq max-mini-window-height 3)))) |
| 117 | |
| 118 | will constrain Emacs to a maximum minibuffer height of 3 lines when |
| 119 | icompletion is occurring." |
| 120 | :type 'hook |
| 121 | :group 'icomplete) |
| 122 | |
| 123 | |
| 124 | ;;;_* Initialization |
| 125 | |
| 126 | ;;;_ + Internal Variables |
| 127 | ;;;_ = icomplete-eoinput nil |
| 128 | (defvar icomplete-overlay (make-overlay (point-min) (point-min) nil t t) |
| 129 | "Overlay used to display the list of completions.") |
| 130 | |
| 131 | ;;;_ = icomplete-pre-command-hook |
| 132 | (defvar icomplete-pre-command-hook nil |
| 133 | "Incremental-minibuffer-completion pre-command-hook. |
| 134 | |
| 135 | Is run in minibuffer before user input when `icomplete-mode' is non-nil. |
| 136 | Use `icomplete-mode' function to set it up properly for incremental |
| 137 | minibuffer completion.") |
| 138 | (add-hook 'icomplete-pre-command-hook 'icomplete-tidy) |
| 139 | ;;;_ = icomplete-post-command-hook |
| 140 | (defvar icomplete-post-command-hook nil |
| 141 | "Incremental-minibuffer-completion post-command-hook. |
| 142 | |
| 143 | Is run in minibuffer after user input when `icomplete-mode' is non-nil. |
| 144 | Use `icomplete-mode' function to set it up properly for incremental |
| 145 | minibuffer completion.") |
| 146 | (add-hook 'icomplete-post-command-hook 'icomplete-exhibit) |
| 147 | |
| 148 | ;;;_ = icomplete-with-completion-tables |
| 149 | (defvar icomplete-with-completion-tables '(internal-complete-buffer) |
| 150 | "Specialized completion tables with which icomplete should operate. |
| 151 | |
| 152 | Icomplete does not operate with any specialized completion tables |
| 153 | except those on this list.") |
| 154 | |
| 155 | (defvar icomplete-minibuffer-map |
| 156 | (let ((map (make-sparse-keymap))) |
| 157 | (define-key map [?\M-\t] 'minibuffer-force-complete) |
| 158 | (define-key map [?\C-j] 'minibuffer-force-complete-and-exit) |
| 159 | (define-key map [?\C-s] 'icomplete-forward-completions) |
| 160 | (define-key map [?\C-r] 'icomplete-backward-completions) |
| 161 | map)) |
| 162 | |
| 163 | (defun icomplete-forward-completions () |
| 164 | "Step forward completions by one entry. |
| 165 | Second entry becomes the first and can be selected with |
| 166 | `minibuffer-force-complete-and-exit'." |
| 167 | (interactive) |
| 168 | (let* ((comps (completion-all-sorted-completions)) |
| 169 | (last (last comps))) |
| 170 | (setcdr last (cons (car comps) (cdr last))) |
| 171 | (completion--cache-all-sorted-completions (cdr comps)))) |
| 172 | |
| 173 | (defun icomplete-backward-completions () |
| 174 | "Step backward completions by one entry. |
| 175 | Last entry becomes the first and can be selected with |
| 176 | `minibuffer-force-complete-and-exit'." |
| 177 | (interactive) |
| 178 | (let* ((comps (completion-all-sorted-completions)) |
| 179 | (last-but-one (last comps 2)) |
| 180 | (last (cdr last-but-one))) |
| 181 | (when last |
| 182 | (setcdr last-but-one (cdr last)) |
| 183 | (push (car last) comps) |
| 184 | (completion--cache-all-sorted-completions comps)))) |
| 185 | |
| 186 | ;;;_ > icomplete-mode (&optional prefix) |
| 187 | ;;;###autoload |
| 188 | (define-minor-mode icomplete-mode |
| 189 | "Toggle incremental minibuffer completion (Icomplete mode). |
| 190 | With a prefix argument ARG, enable Icomplete mode if ARG is |
| 191 | positive, and disable it otherwise. If called from Lisp, enable |
| 192 | the mode if ARG is omitted or nil." |
| 193 | :global t :group 'icomplete |
| 194 | (if icomplete-mode |
| 195 | ;; The following is not really necessary after first time - |
| 196 | ;; no great loss. |
| 197 | (add-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup) |
| 198 | (remove-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup))) |
| 199 | |
| 200 | ;;;_ > icomplete-simple-completing-p () |
| 201 | (defun icomplete-simple-completing-p () |
| 202 | "Non-nil if current window is minibuffer that's doing simple completion. |
| 203 | |
| 204 | Conditions are: |
| 205 | the selected window is a minibuffer, |
| 206 | and not in the middle of macro execution, |
| 207 | and `minibuffer-completion-table' is not a symbol (which would |
| 208 | indicate some non-standard, non-simple completion mechanism, |
| 209 | like file-name and other custom-func completions)." |
| 210 | |
| 211 | (and (window-minibuffer-p (selected-window)) |
| 212 | (not executing-kbd-macro) |
| 213 | minibuffer-completion-table |
| 214 | (or (not (functionp minibuffer-completion-table)) |
| 215 | (eq icomplete-with-completion-tables t) |
| 216 | (member minibuffer-completion-table |
| 217 | icomplete-with-completion-tables)))) |
| 218 | |
| 219 | ;;;_ > icomplete-minibuffer-setup () |
| 220 | (defun icomplete-minibuffer-setup () |
| 221 | "Run in minibuffer on activation to establish incremental completion. |
| 222 | Usually run by inclusion in `minibuffer-setup-hook'." |
| 223 | (when (and icomplete-mode (icomplete-simple-completing-p)) |
| 224 | (set (make-local-variable 'completion-show-inline-help) nil) |
| 225 | (use-local-map (make-composed-keymap icomplete-minibuffer-map |
| 226 | (current-local-map))) |
| 227 | (add-hook 'pre-command-hook |
| 228 | (lambda () (let ((non-essential t)) |
| 229 | (run-hooks 'icomplete-pre-command-hook))) |
| 230 | nil t) |
| 231 | (add-hook 'post-command-hook |
| 232 | (lambda () (let ((non-essential t)) ;E.g. don't prompt for password! |
| 233 | (run-hooks 'icomplete-post-command-hook))) |
| 234 | nil t) |
| 235 | (run-hooks 'icomplete-minibuffer-setup-hook))) |
| 236 | ;\f |
| 237 | |
| 238 | |
| 239 | ;;;_* Completion |
| 240 | |
| 241 | ;;;_ > icomplete-tidy () |
| 242 | (defun icomplete-tidy () |
| 243 | "Remove completions display \(if any) prior to new user input. |
| 244 | Should be run in on the minibuffer `pre-command-hook'. See `icomplete-mode' |
| 245 | and `minibuffer-setup-hook'." |
| 246 | (delete-overlay icomplete-overlay)) |
| 247 | |
| 248 | ;;;_ > icomplete-exhibit () |
| 249 | (defun icomplete-exhibit () |
| 250 | "Insert icomplete completions display. |
| 251 | Should be run via minibuffer `post-command-hook'. See `icomplete-mode' |
| 252 | and `minibuffer-setup-hook'." |
| 253 | (when (and icomplete-mode (icomplete-simple-completing-p)) |
| 254 | (save-excursion |
| 255 | (goto-char (point-max)) |
| 256 | ; Insert the match-status information: |
| 257 | (if (and (> (point-max) (minibuffer-prompt-end)) |
| 258 | buffer-undo-list ; Wait for some user input. |
| 259 | (or |
| 260 | ;; Don't bother with delay after certain number of chars: |
| 261 | (> (- (point) (field-beginning)) icomplete-max-delay-chars) |
| 262 | ;; Don't delay if the completions are known. |
| 263 | completion-all-sorted-completions |
| 264 | ;; Don't delay if alternatives number is small enough: |
| 265 | (and (sequencep minibuffer-completion-table) |
| 266 | (< (length minibuffer-completion-table) |
| 267 | icomplete-delay-completions-threshold)) |
| 268 | ;; Delay - give some grace time for next keystroke, before |
| 269 | ;; embarking on computing completions: |
| 270 | (sit-for icomplete-compute-delay))) |
| 271 | (let ((text (while-no-input |
| 272 | (icomplete-completions |
| 273 | (field-string) |
| 274 | minibuffer-completion-table |
| 275 | minibuffer-completion-predicate |
| 276 | (not minibuffer-completion-confirm)))) |
| 277 | (buffer-undo-list t) |
| 278 | deactivate-mark) |
| 279 | ;; Do nothing if while-no-input was aborted. |
| 280 | (when (stringp text) |
| 281 | (move-overlay icomplete-overlay (point) (point) (current-buffer)) |
| 282 | ;; The current C cursor code doesn't know to use the overlay's |
| 283 | ;; marker's stickiness to figure out whether to place the cursor |
| 284 | ;; before or after the string, so let's spoon-feed it the pos. |
| 285 | (put-text-property 0 1 'cursor t text) |
| 286 | (overlay-put icomplete-overlay 'after-string text))))))) |
| 287 | |
| 288 | ;;;_ > icomplete-completions (name candidates predicate require-match) |
| 289 | (defun icomplete-completions (name candidates predicate require-match) |
| 290 | "Identify prospective candidates for minibuffer completion. |
| 291 | |
| 292 | The display is updated with each minibuffer keystroke during |
| 293 | minibuffer completion. |
| 294 | |
| 295 | Prospective completion suffixes (if any) are displayed, bracketed by |
| 296 | one of \(), \[], or \{} pairs. The choice of brackets is as follows: |
| 297 | |
| 298 | \(...) - a single prospect is identified and matching is enforced, |
| 299 | \[...] - a single prospect is identified but matching is optional, or |
| 300 | \{...} - multiple prospects, separated by commas, are indicated, and |
| 301 | further input is required to distinguish a single one. |
| 302 | |
| 303 | The displays for unambiguous matches have ` [Matched]' appended |
| 304 | \(whether complete or not), or ` \[No matches]', if no eligible |
| 305 | matches exist. \(Keybindings for uniquely matched commands |
| 306 | are exhibited within the square braces.)" |
| 307 | |
| 308 | (let* ((md (completion--field-metadata (field-beginning))) |
| 309 | (comps (completion-all-sorted-completions)) |
| 310 | (last (if (consp comps) (last comps))) |
| 311 | (base-size (cdr last)) |
| 312 | (open-bracket (if require-match "(" "[")) |
| 313 | (close-bracket (if require-match ")" "]"))) |
| 314 | ;; `concat'/`mapconcat' is the slow part. |
| 315 | (if (not (consp comps)) |
| 316 | (format " %sNo matches%s" open-bracket close-bracket) |
| 317 | (if last (setcdr last nil)) |
| 318 | (let* ((most-try |
| 319 | (if (and base-size (> base-size 0)) |
| 320 | (completion-try-completion |
| 321 | name candidates predicate (length name) md) |
| 322 | ;; If the `comps' are 0-based, the result should be |
| 323 | ;; the same with `comps'. |
| 324 | (completion-try-completion |
| 325 | name comps nil (length name) md))) |
| 326 | (most (if (consp most-try) (car most-try) |
| 327 | (if most-try (car comps) ""))) |
| 328 | ;; Compare name and most, so we can determine if name is |
| 329 | ;; a prefix of most, or something else. |
| 330 | (compare (compare-strings name nil nil |
| 331 | most nil nil completion-ignore-case)) |
| 332 | (determ (unless (or (eq t compare) (eq t most-try) |
| 333 | (= (setq compare (1- (abs compare))) |
| 334 | (length most))) |
| 335 | (concat open-bracket |
| 336 | (cond |
| 337 | ((= compare (length name)) |
| 338 | ;; Typical case: name is a prefix. |
| 339 | (substring most compare)) |
| 340 | ((< compare 5) most) |
| 341 | (t (concat "..." (substring most compare)))) |
| 342 | close-bracket))) |
| 343 | ;;"-prospects" - more than one candidate |
| 344 | (prospects-len (+ (length determ) 6 ;; take {,...} into account |
| 345 | (string-width (buffer-string)))) |
| 346 | (prospects-max |
| 347 | ;; Max total length to use, including the minibuffer content. |
| 348 | (* (+ icomplete-prospects-height |
| 349 | ;; If the minibuffer content already uses up more than |
| 350 | ;; one line, increase the allowable space accordingly. |
| 351 | (/ prospects-len (window-width))) |
| 352 | (window-width))) |
| 353 | (prefix-len |
| 354 | ;; Find the common prefix among `comps'. |
| 355 | ;; We can't use the optimization below because its assumptions |
| 356 | ;; aren't always true, e.g. when completion-cycling (bug#10850): |
| 357 | ;; (if (eq t (compare-strings (car comps) nil (length most) |
| 358 | ;; most nil nil completion-ignore-case)) |
| 359 | ;; ;; Common case. |
| 360 | ;; (length most) |
| 361 | ;; Else, use try-completion. |
| 362 | (let ((comps-prefix (try-completion "" comps))) |
| 363 | (and (stringp comps-prefix) |
| 364 | (length comps-prefix)))) ;;) |
| 365 | |
| 366 | prospects most-is-exact comp limit) |
| 367 | (if (eq most-try t) ;; (or (null (cdr comps)) |
| 368 | (setq prospects nil) |
| 369 | (while (and comps (not limit)) |
| 370 | (setq comp |
| 371 | (if prefix-len (substring (car comps) prefix-len) (car comps)) |
| 372 | comps (cdr comps)) |
| 373 | (cond ((string-equal comp "") (setq most-is-exact t)) |
| 374 | ((member comp prospects)) |
| 375 | (t (setq prospects-len |
| 376 | (+ (string-width comp) 1 prospects-len)) |
| 377 | (if (< prospects-len prospects-max) |
| 378 | (push comp prospects) |
| 379 | (setq limit t)))))) |
| 380 | ;; Restore the base-size info, since completion-all-sorted-completions |
| 381 | ;; is cached. |
| 382 | (if last (setcdr last base-size)) |
| 383 | (if prospects |
| 384 | (concat determ |
| 385 | "{" |
| 386 | (and most-is-exact |
| 387 | (substring icomplete-separator |
| 388 | (string-match "[^ ]" icomplete-separator))) |
| 389 | (mapconcat 'identity (nreverse prospects) |
| 390 | icomplete-separator) |
| 391 | (and limit (concat icomplete-separator "…")) |
| 392 | "}") |
| 393 | (concat determ " [Matched]")))))) |
| 394 | |
| 395 | ;;_* Local emacs vars. |
| 396 | ;;Local variables: |
| 397 | ;;allout-layout: (-2 :) |
| 398 | ;;End: |
| 399 | |
| 400 | ;;; icomplete.el ends here |