lisp/icomplete.el

   1 ;;; icomplete.el --- minibuffer completion incremental feedback
   2
   3 ;; Copyright (C) 1992-1994, 1997, 1999, 2001-2013 Free Software
   4 ;; 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.4")
  78
  79 (defcustom icomplete-hide-common-prefix t
  80   "When non-nil, hide common prefix from completion candidates.
  81 When nil, show candidates in full."
  82   :type 'boolean
  83   :version "24.4"
  84   :group 'icomplete)
  85
  86 (defface icomplete-first-match  '((t :weight bold))
  87   "Face used by icomplete for highlighting first match."
  88   :version "24.4"
  89   :group 'icomplete)
  90
  91 ;;;_* User Customization variables
  92 (defcustom icomplete-prospects-height
  93   ;; 20 is an estimated common size for the prompt + minibuffer content, to
  94   ;; try to guess the number of lines used up by icomplete-prospects-length.
  95   (+ 1 (/ (+ icomplete-prospects-length 20) (window-width)))
  96   "Maximum number of lines to use in the minibuffer."
  97   :type 'integer
  98   :group 'icomplete
  99   :version "23.1")
 100
 101 (defcustom icomplete-compute-delay .3
 102   "Completions-computation stall, used only with large-number completions.
 103 See `icomplete-delay-completions-threshold'."
 104   :type 'number
 105   :group 'icomplete)
 106
 107 (defcustom icomplete-delay-completions-threshold 400
 108   "Pending-completions number over which to apply `icomplete-compute-delay'."
 109   :type 'integer
 110   :group 'icomplete)
 111
 112 (defcustom icomplete-max-delay-chars 3
 113   "Maximum number of initial chars to apply icomplete compute delay."
 114   :type 'integer
 115   :group 'icomplete)
 116
 117 (defcustom icomplete-minibuffer-setup-hook nil
 118   "Icomplete-specific customization of minibuffer setup.
 119
 120 This hook is run during minibuffer setup if icomplete is active.
 121 It is intended for use in customizing icomplete for interoperation
 122 with other features and packages.  For instance:
 123
 124   \(add-hook 'icomplete-minibuffer-setup-hook
 125             \(function
 126              \(lambda ()
 127                \(make-local-variable 'max-mini-window-height)
 128                \(setq max-mini-window-height 3))))
 129
 130 will constrain Emacs to a maximum minibuffer height of 3 lines when
 131 icompletion is occurring."
 132   :type 'hook
 133   :group 'icomplete)
 134
 135
 136 ;;;_* Initialization
 137
 138 ;;;_ + Internal Variables
 139 ;;;_  = icomplete-eoinput nil
 140 (defvar icomplete-overlay (make-overlay (point-min) (point-min) nil t t)
 141   "Overlay used to display the list of completions.")
 142
 143 ;;;_  = icomplete-pre-command-hook
 144 (defvar icomplete-pre-command-hook nil
 145   "Incremental-minibuffer-completion pre-command-hook.
 146
 147 Is run in minibuffer before user input when `icomplete-mode' is non-nil.
 148 Use `icomplete-mode' function to set it up properly for incremental
 149 minibuffer completion.")
 150 (add-hook 'icomplete-pre-command-hook 'icomplete-tidy)
 151 ;;;_  = icomplete-post-command-hook
 152 (defvar icomplete-post-command-hook nil
 153   "Incremental-minibuffer-completion post-command-hook.
 154
 155 Is run in minibuffer after user input when `icomplete-mode' is non-nil.
 156 Use `icomplete-mode' function to set it up properly for incremental
 157 minibuffer completion.")
 158 (add-hook 'icomplete-post-command-hook 'icomplete-exhibit)
 159
 160 ;;;_  = icomplete-with-completion-tables
 161 (defcustom icomplete-with-completion-tables t
 162   "Specialized completion tables with which icomplete should operate.
 163
 164 Icomplete does not operate with any specialized completion tables
 165 except those on this list."
 166   :type '(choice (const :tag "All" t)
 167           (repeat function)))
 168
 169 (defvar icomplete-minibuffer-map
 170   (let ((map (make-sparse-keymap)))
 171     (define-key map [?\M-\t] 'minibuffer-force-complete)
 172     (define-key map [?\C-j]  'minibuffer-force-complete-and-exit)
 173     (define-key map [?\C-.]  'icomplete-forward-completions)
 174     (define-key map [?\C-,]  'icomplete-backward-completions)
 175     map))
 176
 177 (defun icomplete-forward-completions ()
 178   "Step forward completions by one entry.
 179 Second entry becomes the first and can be selected with
 180 `minibuffer-force-complete-and-exit'."
 181   (interactive)
 182   (let* ((beg (minibuffer-prompt-end))
 183          (end (point-max))
 184          (comps (completion-all-sorted-completions beg end))
 185          (last (last comps)))
 186     (when comps
 187       (setcdr last (cons (car comps) (cdr last)))
 188       (completion--cache-all-sorted-completions beg end (cdr comps)))))
 189
 190 (defun icomplete-backward-completions ()
 191   "Step backward completions by one entry.
 192 Last entry becomes the first and can be selected with
 193 `minibuffer-force-complete-and-exit'."
 194   (interactive)
 195   (let* ((beg (minibuffer-prompt-end))
 196          (end (point-max))
 197          (comps (completion-all-sorted-completions beg end))
 198          (last-but-one (last comps 2))
 199          (last (cdr last-but-one)))
 200     (when (consp last)                ; At least two elements in comps
 201       (setcdr last-but-one (cdr last))
 202       (push (car last) comps)
 203       (completion--cache-all-sorted-completions beg end comps))))
 204
 205 ;;;_ > icomplete-mode (&optional prefix)
 206 ;;;###autoload
 207 (define-minor-mode icomplete-mode
 208   "Toggle incremental minibuffer completion (Icomplete mode).
 209 With a prefix argument ARG, enable Icomplete mode if ARG is
 210 positive, and disable it otherwise.  If called from Lisp, enable
 211 the mode if ARG is omitted or nil."
 212   :global t :group 'icomplete
 213   (if icomplete-mode
 214       ;; The following is not really necessary after first time -
 215       ;; no great loss.
 216       (add-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup)
 217     (remove-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup)))
 218
 219 ;;;_ > icomplete-simple-completing-p ()
 220 (defun icomplete-simple-completing-p ()
 221   "Non-nil if current window is minibuffer that's doing simple completion.
 222
 223 Conditions are:
 224    the selected window is a minibuffer,
 225    and not in the middle of macro execution,
 226    and `minibuffer-completion-table' is not a symbol (which would
 227        indicate some non-standard, non-simple completion mechanism,
 228        like file-name and other custom-func completions)."
 229
 230   (and (window-minibuffer-p)
 231        (not executing-kbd-macro)
 232        minibuffer-completion-table
 233        (or (not (functionp minibuffer-completion-table))
 234            (eq icomplete-with-completion-tables t)
 235            (member minibuffer-completion-table
 236                    icomplete-with-completion-tables))))
 237
 238 ;;;_ > icomplete-minibuffer-setup ()
 239 (defun icomplete-minibuffer-setup ()
 240   "Run in minibuffer on activation to establish incremental completion.
 241 Usually run by inclusion in `minibuffer-setup-hook'."
 242   (when (and icomplete-mode (icomplete-simple-completing-p))
 243     (set (make-local-variable 'completion-show-inline-help) nil)
 244     (use-local-map (make-composed-keymap icomplete-minibuffer-map
 245                                          (current-local-map)))
 246     (add-hook 'pre-command-hook
 247               (lambda () (let ((non-essential t))
 248                       (run-hooks 'icomplete-pre-command-hook)))
 249               nil t)
 250     (add-hook 'post-command-hook
 251               (lambda () (let ((non-essential t)) ;E.g. don't prompt for password!
 252                       (run-hooks 'icomplete-post-command-hook)))
 253               nil t)
 254     (run-hooks 'icomplete-minibuffer-setup-hook)))
 255 ;\f
 256
 257
 258 ;;;_* Completion
 259
 260 ;;;_ > icomplete-tidy ()
 261 (defun icomplete-tidy ()
 262   "Remove completions display \(if any) prior to new user input.
 263 Should be run in on the minibuffer `pre-command-hook'.  See `icomplete-mode'
 264 and `minibuffer-setup-hook'."
 265   (delete-overlay icomplete-overlay))
 266
 267 ;;;_ > icomplete-exhibit ()
 268 (defun icomplete-exhibit ()
 269   "Insert icomplete completions display.
 270 Should be run via minibuffer `post-command-hook'.  See `icomplete-mode'
 271 and `minibuffer-setup-hook'."
 272   (when (and icomplete-mode
 273              (icomplete-simple-completing-p)) ;Shouldn't be necessary.
 274     (save-excursion
 275       (goto-char (point-max))
 276                                         ; Insert the match-status information:
 277       (if (and (> (point-max) (minibuffer-prompt-end))
 278                buffer-undo-list         ; Wait for some user input.
 279                (or
 280                 ;; Don't bother with delay after certain number of chars:
 281                 (> (- (point) (field-beginning)) icomplete-max-delay-chars)
 282                 ;; Don't delay if the completions are known.
 283                 completion-all-sorted-completions
 284                 ;; Don't delay if alternatives number is small enough:
 285                 (and (sequencep minibuffer-completion-table)
 286                      (< (length minibuffer-completion-table)
 287                         icomplete-delay-completions-threshold))
 288                 ;; Delay - give some grace time for next keystroke, before
 289                 ;; embarking on computing completions:
 290                 (sit-for icomplete-compute-delay)))
 291           (let ((text (while-no-input
 292                         (icomplete-completions
 293                          (field-string)
 294                          minibuffer-completion-table
 295                          minibuffer-completion-predicate
 296                          (not minibuffer-completion-confirm))))
 297                 (buffer-undo-list t)
 298                 deactivate-mark)
 299             ;; Do nothing if while-no-input was aborted.
 300             (when (stringp text)
 301               (move-overlay icomplete-overlay (point) (point) (current-buffer))
 302               ;; The current C cursor code doesn't know to use the overlay's
 303               ;; marker's stickiness to figure out whether to place the cursor
 304               ;; before or after the string, so let's spoon-feed it the pos.
 305               (put-text-property 0 1 'cursor t text)
 306               (overlay-put icomplete-overlay 'after-string text)))))))
 307
 308 ;;;_ > icomplete-completions (name candidates predicate require-match)
 309 (defun icomplete-completions (name candidates predicate require-match)
 310   "Identify prospective candidates for minibuffer completion.
 311
 312 The display is updated with each minibuffer keystroke during
 313 minibuffer completion.
 314
 315 Prospective completion suffixes (if any) are displayed, bracketed by
 316 one of \(), \[], or \{} pairs.  The choice of brackets is as follows:
 317
 318   \(...) - a single prospect is identified and matching is enforced,
 319   \[...] - a single prospect is identified but matching is optional, or
 320   \{...} - multiple prospects, separated by commas, are indicated, and
 321           further input is required to distinguish a single one.
 322
 323 The displays for unambiguous matches have ` [Matched]' appended
 324 \(whether complete or not), or ` \[No matches]', if no eligible
 325 matches exist.  \(Keybindings for uniquely matched commands
 326 are exhibited within the square braces.)"
 327
 328   (let* ((md (completion--field-metadata (field-beginning)))
 329          (comps (completion-all-sorted-completions
 330                  (minibuffer-prompt-end) (point-max)))
 331          (last (if (consp comps) (last comps)))
 332          (base-size (cdr last))
 333          (open-bracket (if require-match "(" "["))
 334          (close-bracket (if require-match ")" "]")))
 335     ;; `concat'/`mapconcat' is the slow part.
 336     (if (not (consp comps))
 337         (format " %sNo matches%s" open-bracket close-bracket)
 338       (if last (setcdr last nil))
 339       (let* ((most-try
 340               (if (and base-size (> base-size 0))
 341                   (completion-try-completion
 342                    name candidates predicate (length name) md)
 343                 ;; If the `comps' are 0-based, the result should be
 344                 ;; the same with `comps'.
 345                 (completion-try-completion
 346                  name comps nil (length name) md)))
 347              (most (if (consp most-try) (car most-try)
 348                      (if most-try (car comps) "")))
 349              ;; Compare name and most, so we can determine if name is
 350              ;; a prefix of most, or something else.
 351              (compare (compare-strings name nil nil
 352                                        most nil nil completion-ignore-case))
 353              (determ (unless (or (eq t compare) (eq t most-try)
 354                                  (= (setq compare (1- (abs compare)))
 355                                     (length most)))
 356                        (concat open-bracket
 357                                (cond
 358                                 ((= compare (length name))
 359                                  ;; Typical case: name is a prefix.
 360                                  (substring most compare))
 361                                 ;; Don't bother truncating if it doesn't gain
 362                                 ;; us at least 2 columns.
 363                                 ((< compare 3) most)
 364                                 (t (concat "…" (substring most compare))))
 365                                close-bracket)))
 366              ;;"-prospects" - more than one candidate
 367              (prospects-len (+ (string-width
 368                                 (or determ (concat open-bracket close-bracket)))
 369                                (string-width icomplete-separator)
 370                                3 ;; take {…} into account
 371                                (string-width (buffer-string))))
 372              (prospects-max
 373               ;; Max total length to use, including the minibuffer content.
 374               (* (+ icomplete-prospects-height
 375                     ;; If the minibuffer content already uses up more than
 376                     ;; one line, increase the allowable space accordingly.
 377                     (/ prospects-len (window-width)))
 378                  (window-width)))
 379              (prefix (when icomplete-hide-common-prefix
 380                        (try-completion "" comps)))
 381              (prefix-len
 382               ;; Find the common prefix among `comps'.
 383               ;; We can't use the optimization below because its assumptions
 384               ;; aren't always true, e.g. when completion-cycling (bug#10850):
 385               ;; (if (eq t (compare-strings (car comps) nil (length most)
 386               ;;                         most nil nil completion-ignore-case))
 387               ;;     ;; Common case.
 388               ;;     (length most)
 389               ;; Else, use try-completion.
 390               (and (stringp prefix) (length prefix))) ;;)
 391              prospects comp limit)
 392         (if (eq most-try t) ;; (or (null (cdr comps))
 393             (setq prospects nil)
 394           (when (member name comps)
 395             ;; NAME is complete but not unique.  This scenario poses
 396             ;; following UI issues:
 397             ;;
 398             ;; - When `icomplete-hide-common-prefix' is non-nil, NAME
 399             ;;   is stripped empty.  This would make the entry
 400             ;;   inconspicuous.
 401             ;;
 402             ;; - Due to sorting of completions, NAME may not be the
 403             ;;   first of the prospects and could be hidden deep in
 404             ;;   the displayed string.
 405             ;;
 406             ;; - Because of `icomplete-prospects-height' , NAME may
 407             ;;   not even be displayed to the user.
 408             ;;
 409             ;; To circumvent all the above problems, provide a visual
 410             ;; cue to the user via an "empty string" in the try
 411             ;; completion field.
 412             (setq determ (concat open-bracket "" close-bracket)))
 413           ;; Compute prospects for display.
 414           (while (and comps (not limit))
 415             (setq comp
 416                   (if prefix-len (substring (car comps) prefix-len) (car comps))
 417                   comps (cdr comps))
 418             (setq prospects-len
 419                            (+ (string-width comp)
 420                               (string-width icomplete-separator)
 421                               prospects-len))
 422                      (if (< prospects-len prospects-max)
 423                          (push comp prospects)
 424               (setq limit t))))
 425         (setq prospects (nreverse prospects))
 426         ;; Decorate first of the prospects.
 427         (when prospects
 428           (let ((first (copy-sequence (pop prospects))))
 429             (put-text-property 0 (length first)
 430                                'face 'icomplete-first-match first)
 431             (push first prospects)))
 432         ;; Restore the base-size info, since completion-all-sorted-completions
 433         ;; is cached.
 434         (if last (setcdr last base-size))
 435         (if prospects
 436             (concat determ
 437                     "{"
 438                     (mapconcat 'identity prospects icomplete-separator)
 439                     (and limit (concat icomplete-separator "…"))
 440                     "}")
 441           (concat determ " [Matched]"))))))
 442
 443 ;;_* Local emacs vars.
 444 ;;Local variables:
 445 ;;allout-layout: (-2 :)
 446 ;;End:
 447
 448 ;;; icomplete.el ends here