lisp/icomplete.el

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