lisp/icomplete.el

   1 ;;; icomplete.el --- minibuffer completion incremental feedback
   2
   3 ;; Copyright (C) 1992-1994, 1997, 1999, 2001-2015 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 ;; Keywords: help, abbrev
  10
  11 ;; This file is part of GNU Emacs.
  12
  13 ;; GNU Emacs 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
  16 ;; (at your option) any later version.
  17
  18 ;; GNU Emacs 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 GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  25
  26 ;;; Commentary:
  27
  28 ;; Enabling this package implements a more fine-grained minibuffer
  29 ;; completion feedback scheme.  Prospective completions are concisely
  30 ;; indicated within the minibuffer itself, with each successive
  31 ;; keystroke.
  32
  33 ;; See `icomplete-completions' docstring for a description of the
  34 ;; icomplete display format.
  35
  36 ;; See the `icomplete-minibuffer-setup-hook' docstring for a means to
  37 ;; customize icomplete setup for interoperation with other
  38 ;; minibuffer-oriented packages.
  39
  40 ;; To enable/disable icomplete mode, use the `icomplete-mode' function.
  41
  42 ;; Thanks to everyone for their suggestions for refinements of this
  43 ;; package.  I particularly have to credit Michael Cook, who
  44 ;; implemented an incremental completion style in his 'iswitch'
  45 ;; functions that served as a model for icomplete.  Some other
  46 ;; contributors: Noah Friedman (restructuring as minor mode), Colin
  47 ;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and others.
  48
  49 ;; klm.
  50
  51 ;;; Code:
  52
  53 (defgroup icomplete nil
  54   "Show completions dynamically in minibuffer."
  55   :prefix "icomplete-"
  56   :link '(info-link "(emacs)Icomplete")
  57   :group 'minibuffer)
  58
  59 (defvar icomplete-prospects-length 80)
  60 (make-obsolete-variable
  61  'icomplete-prospects-length 'icomplete-prospects-height "23.1")
  62
  63 (defcustom icomplete-separator " | "
  64   "String used by Icomplete to separate alternatives in the minibuffer."
  65   :type 'string
  66   :version "24.4")
  67
  68 (defcustom icomplete-hide-common-prefix t
  69   "When non-nil, hide common prefix from completion candidates.
  70 When nil, show candidates in full."
  71   :type 'boolean
  72   :version "24.4")
  73
  74 (defcustom icomplete-show-matches-on-no-input nil
  75   "When non-nil, show completions when first prompting for input."
  76   :type 'boolean
  77   :version "24.4")
  78
  79 (defcustom icomplete-with-completion-tables t
  80   "Specialized completion tables with which Icomplete should operate.
  81 If this is t, Icomplete operates on all tables.
  82 Otherwise this should be a list of the completion tables (e.g.,
  83 `internal-complete-buffer') on which Icomplete should operate."
  84   ;; Prior to 24.4, not a user-option, default '(internal-complete-buffer).
  85   :version "24.4"
  86   :type '(choice (const :tag "All" t)
  87                  (repeat function)))
  88
  89 (defface icomplete-first-match '((t :weight bold))
  90   "Face used by Icomplete for highlighting first match."
  91   :version "24.4")
  92
  93 ;;;_* User Customization variables
  94 (defcustom icomplete-prospects-height
  95   ;; 20 is an estimated common size for the prompt + minibuffer content, to
  96   ;; try to guess the number of lines used up by icomplete-prospects-length.
  97   (+ 1 (/ (+ icomplete-prospects-length 20) (window-width)))
  98   "Maximum number of lines to use in the minibuffer."
  99   :type 'integer
 100   :version "23.1")
 101
 102 (defcustom icomplete-compute-delay .3
 103   "Completions-computation stall, used only with large-number completions.
 104 See `icomplete-delay-completions-threshold'."
 105   :type 'number)
 106
 107 (defcustom icomplete-delay-completions-threshold 400
 108   "Pending-completions number over which to apply `icomplete-compute-delay'."
 109   :type 'integer)
 110
 111 (defcustom icomplete-max-delay-chars 3
 112   "Maximum number of initial chars to apply `icomplete-compute-delay'."
 113   :type 'integer)
 114
 115 (defvar icomplete-in-buffer nil
 116   "If non-nil, also use Icomplete when completing in non-mini buffers.")
 117
 118 (defcustom icomplete-minibuffer-setup-hook nil
 119   "Icomplete-specific customization of minibuffer setup.
 120
 121 This hook is run during minibuffer setup if Icomplete is active.
 122 It is intended for use in customizing Icomplete for interoperation
 123 with other features and packages.  For instance:
 124
 125   (add-hook 'icomplete-minibuffer-setup-hook
 126              (lambda () (setq-local 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 (defvar icomplete-minibuffer-map
 150   (let ((map (make-sparse-keymap)))
 151     (define-key map [?\M-\t] 'minibuffer-force-complete)
 152     (define-key map [?\C-j]  'icomplete-force-complete-and-exit)
 153     (define-key map [?\C-.]  'icomplete-forward-completions)
 154     (define-key map [?\C-,]  'icomplete-backward-completions)
 155     map)
 156   "Keymap used by `icomplete-mode' in the minibuffer.")
 157
 158 (defun icomplete-force-complete-and-exit ()
 159   "Complete the minibuffer and exit.
 160 Use the first of the matches if there are any displayed, and use
 161 the default otherwise."
 162   (interactive)
 163   (if (or icomplete-show-matches-on-no-input
 164           (> (icomplete--field-end) (icomplete--field-beg)))
 165       (minibuffer-force-complete-and-exit)
 166     (minibuffer-complete-and-exit)))
 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 `icomplete-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 `icomplete-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
 204 When this global minor mode is enabled, typing in the minibuffer
 205 continuously displays a list of possible completions that match
 206 the string you have typed.  See `icomplete-completions' for a
 207 description of how prospective completions are displayed.
 208
 209 For more information, see Info node `(emacs)Icomplete'.
 210 For options you can set, `\\[customize-group] icomplete'.
 211
 212 You can use the following key bindings to navigate and select
 213 completions:
 214
 215 \\{icomplete-minibuffer-map}"
 216   :global t :group 'icomplete
 217   (remove-hook 'minibuffer-setup-hook #'icomplete-minibuffer-setup)
 218   (remove-hook 'completion-in-region-mode-hook #'icomplete--in-region-setup)
 219   (when icomplete-mode
 220     (when icomplete-in-buffer
 221       (add-hook 'completion-in-region-mode-hook #'icomplete--in-region-setup))
 222     (add-hook 'minibuffer-setup-hook #'icomplete-minibuffer-setup)))
 223
 224 (defun icomplete--completion-table ()
 225   (if (window-minibuffer-p) minibuffer-completion-table
 226     (or (nth 2 completion-in-region--data)
 227         (message "In %S (w=%S): %S"
 228                  (current-buffer) (selected-window) (window-minibuffer-p)))))
 229 (defun icomplete--completion-predicate ()
 230   (if (window-minibuffer-p) minibuffer-completion-predicate
 231     (nth 3 completion-in-region--data)))
 232 (defun icomplete--field-string ()
 233   (if (window-minibuffer-p) (minibuffer-contents)
 234     (buffer-substring-no-properties
 235      (nth 0 completion-in-region--data)
 236      (nth 1 completion-in-region--data))))
 237 (defun icomplete--field-beg ()
 238   (if (window-minibuffer-p) (minibuffer-prompt-end)
 239     (nth 0 completion-in-region--data)))
 240 (defun icomplete--field-end ()
 241   (if (window-minibuffer-p) (point-max)
 242     (nth 1 completion-in-region--data)))
 243
 244 ;;;_ > icomplete-simple-completing-p ()
 245 (defun icomplete-simple-completing-p ()
 246   "Non-nil if current window is a minibuffer that's doing simple completion.
 247
 248 Conditions are:
 249    the selected window is a minibuffer,
 250    and not in the middle of macro execution,
 251    and the completion table is not a function (which would
 252        indicate some non-standard, non-simple completion mechanism,
 253        like file-name and other custom-func completions),
 254    and `icomplete-with-completion-tables' doesn't restrict completion."
 255
 256   (unless executing-kbd-macro
 257     (let ((table (icomplete--completion-table)))
 258       (and table
 259            (or (not (functionp table))
 260                (eq icomplete-with-completion-tables t)
 261                (member table icomplete-with-completion-tables))))))
 262
 263 ;;;_ > icomplete-minibuffer-setup ()
 264 (defun icomplete-minibuffer-setup ()
 265   "Run in minibuffer on activation to establish incremental completion.
 266 Usually run by inclusion in `minibuffer-setup-hook'."
 267   (when (and icomplete-mode (icomplete-simple-completing-p))
 268     (set (make-local-variable 'completion-show-inline-help) nil)
 269     (use-local-map (make-composed-keymap icomplete-minibuffer-map
 270                                          (current-local-map)))
 271     (add-hook 'pre-command-hook  #'icomplete-pre-command-hook  nil t)
 272     (add-hook 'post-command-hook #'icomplete-post-command-hook nil t)
 273     (run-hooks 'icomplete-minibuffer-setup-hook)
 274     (when icomplete-show-matches-on-no-input
 275       (icomplete-exhibit))))
 276
 277 (defvar icomplete--in-region-buffer nil)
 278
 279 (defun icomplete--in-region-setup ()
 280   (when (or (not completion-in-region-mode)
 281             (and icomplete--in-region-buffer
 282                  (not (eq icomplete--in-region-buffer (current-buffer)))))
 283     (with-current-buffer (or icomplete--in-region-buffer (current-buffer))
 284       (setq icomplete--in-region-buffer nil)
 285       (delete-overlay icomplete-overlay)
 286       (kill-local-variable 'completion-show-inline-help)
 287       (remove-hook 'pre-command-hook  'icomplete-pre-command-hook  t)
 288       (remove-hook 'post-command-hook 'icomplete-post-command-hook t)
 289       (message nil)))
 290   (when (and completion-in-region-mode
 291              icomplete-mode (icomplete-simple-completing-p))
 292     (setq icomplete--in-region-buffer (current-buffer))
 293     (set (make-local-variable 'completion-show-inline-help) nil)
 294     (let ((tem (assq 'completion-in-region-mode
 295                      minor-mode-overriding-map-alist)))
 296       (unless (memq icomplete-minibuffer-map (cdr tem))
 297         (setcdr tem (make-composed-keymap icomplete-minibuffer-map
 298                                           (cdr tem)))))
 299     (add-hook 'pre-command-hook  'icomplete-pre-command-hook  nil t)
 300     (add-hook 'post-command-hook 'icomplete-post-command-hook nil t)))
 301 \f
 302
 303
 304 ;;;_* Completion
 305
 306 ;;;_ > icomplete-tidy ()
 307 (defun icomplete-tidy ()
 308   "Remove completions display (if any) prior to new user input.
 309 Should be run in on the minibuffer `pre-command-hook'.
 310 See `icomplete-mode' and `minibuffer-setup-hook'."
 311   (delete-overlay icomplete-overlay))
 312
 313 ;;;_ > icomplete-exhibit ()
 314 (defun icomplete-exhibit ()
 315   "Insert Icomplete completions display.
 316 Should be run via minibuffer `post-command-hook'.
 317 See `icomplete-mode' and `minibuffer-setup-hook'."
 318   (when (and icomplete-mode
 319              (icomplete-simple-completing-p)) ;Shouldn't be necessary.
 320     (save-excursion
 321       (goto-char (point-max))
 322                                         ; Insert the match-status information:
 323       (if (and (or icomplete-show-matches-on-no-input
 324                    (> (icomplete--field-end) (icomplete--field-beg)))
 325                (or
 326                 ;; Don't bother with delay after certain number of chars:
 327                 (> (- (point) (icomplete--field-beg))
 328                    icomplete-max-delay-chars)
 329                 ;; Don't delay if the completions are known.
 330                 completion-all-sorted-completions
 331                 ;; Don't delay if alternatives number is small enough:
 332                 (and (sequencep (icomplete--completion-table))
 333                      (< (length (icomplete--completion-table))
 334                         icomplete-delay-completions-threshold))
 335                 ;; Delay - give some grace time for next keystroke, before
 336                 ;; embarking on computing completions:
 337                 (sit-for icomplete-compute-delay)))
 338           (let* ((field-string (icomplete--field-string))
 339                  (text (while-no-input
 340                          (icomplete-completions
 341                           field-string
 342                           (icomplete--completion-table)
 343                           (icomplete--completion-predicate)
 344                           (if (window-minibuffer-p)
 345                               (not minibuffer-completion-confirm)))))
 346                  (buffer-undo-list t)
 347                  deactivate-mark)
 348             ;; Do nothing if while-no-input was aborted.
 349             (when (stringp text)
 350               (move-overlay icomplete-overlay (point) (point) (current-buffer))
 351               ;; The current C cursor code doesn't know to use the overlay's
 352               ;; marker's stickiness to figure out whether to place the cursor
 353               ;; before or after the string, so let's spoon-feed it the pos.
 354               (put-text-property 0 1 'cursor t text)
 355               (overlay-put icomplete-overlay 'after-string text)))))))
 356
 357 ;;;_ > icomplete-completions (name candidates predicate require-match)
 358 (defun icomplete-completions (name candidates predicate require-match)
 359   "Identify prospective candidates for minibuffer completion.
 360
 361 The display is updated with each minibuffer keystroke during
 362 minibuffer completion.
 363
 364 Prospective completion suffixes (if any) are displayed, bracketed by
 365 one of (), [], or {} pairs.  The choice of brackets is as follows:
 366
 367   (...) - a single prospect is identified and matching is enforced,
 368   [...] - a single prospect is identified but matching is optional, or
 369   {...} - multiple prospects, separated by commas, are indicated, and
 370           further input is required to distinguish a single one.
 371
 372 If there are multiple possibilities, `icomplete-separator' separates them.
 373
 374 The displays for unambiguous matches have ` [Matched]' appended
 375 \(whether complete or not), or ` [No matches]', if no eligible
 376 matches exist."
 377   (let* ((minibuffer-completion-table candidates)
 378          (minibuffer-completion-predicate predicate)
 379          (md (completion--field-metadata (icomplete--field-beg)))
 380          (comps (completion-all-sorted-completions
 381                  (icomplete--field-beg) (icomplete--field-end)))
 382          (last (if (consp comps) (last comps)))
 383          (base-size (cdr last))
 384          (open-bracket (if require-match "(" "["))
 385          (close-bracket (if require-match ")" "]")))
 386     ;; `concat'/`mapconcat' is the slow part.
 387     (if (not (consp comps))
 388         (progn ;;(debug (format "Candidates=%S field=%S" candidates name))
 389                (format " %sNo matches%s" open-bracket close-bracket))
 390       (if last (setcdr last nil))
 391       (let* ((most-try
 392               (if (and base-size (> base-size 0))
 393                   (completion-try-completion
 394                    name candidates predicate (length name) md)
 395                 ;; If the `comps' are 0-based, the result should be
 396                 ;; the same with `comps'.
 397                 (completion-try-completion
 398                  name comps nil (length name) md)))
 399              (most (if (consp most-try) (car most-try)
 400                      (if most-try (car comps) "")))
 401              ;; Compare name and most, so we can determine if name is
 402              ;; a prefix of most, or something else.
 403              (compare (compare-strings name nil nil
 404                                        most nil nil completion-ignore-case))
 405              (ellipsis (if (char-displayable-p ?…) "…" "..."))
 406              (determ (unless (or (eq t compare) (eq t most-try)
 407                                  (= (setq compare (1- (abs compare)))
 408                                     (length most)))
 409                        (concat open-bracket
 410                                (cond
 411                                 ((= compare (length name))
 412                                  ;; Typical case: name is a prefix.
 413                                  (substring most compare))
 414                                 ;; Don't bother truncating if it doesn't gain
 415                                 ;; us at least 2 columns.
 416                                 ((< compare (+ 2 (string-width ellipsis))) most)
 417                                 (t (concat ellipsis (substring most compare))))
 418                                close-bracket)))
 419              ;;"-prospects" - more than one candidate
 420              (prospects-len (+ (string-width
 421                                 (or determ (concat open-bracket close-bracket)))
 422                                (string-width icomplete-separator)
 423                                (+ 2 (string-width ellipsis)) ;; take {…} into account
 424                                (string-width (buffer-string))))
 425              (prospects-max
 426               ;; Max total length to use, including the minibuffer content.
 427               (* (+ icomplete-prospects-height
 428                     ;; If the minibuffer content already uses up more than
 429                     ;; one line, increase the allowable space accordingly.
 430                     (/ prospects-len (window-width)))
 431                  (window-width)))
 432              ;; Find the common prefix among `comps'.
 433              ;; We can't use the optimization below because its assumptions
 434              ;; aren't always true, e.g. when completion-cycling (bug#10850):
 435              ;; (if (eq t (compare-strings (car comps) nil (length most)
 436              ;;                          most nil nil completion-ignore-case))
 437              ;;     ;; Common case.
 438              ;;     (length most)
 439              ;; Else, use try-completion.
 440              (prefix (when icomplete-hide-common-prefix
 441                        (try-completion "" comps)))
 442              (prefix-len
 443               (and (stringp prefix)
 444                    ;; Only hide the prefix if the corresponding info
 445                    ;; is already displayed via `most'.
 446                    (string-prefix-p prefix most t)
 447                    (length prefix))) ;;)
 448              prospects comp limit)
 449         (if (or (eq most-try t) (not (consp (cdr comps))))
 450             (setq prospects nil)
 451           (when (member name comps)
 452             ;; NAME is complete but not unique.  This scenario poses
 453             ;; following UI issues:
 454             ;;
 455             ;; - When `icomplete-hide-common-prefix' is non-nil, NAME
 456             ;;   is stripped empty.  This would make the entry
 457             ;;   inconspicuous.
 458             ;;
 459             ;; - Due to sorting of completions, NAME may not be the
 460             ;;   first of the prospects and could be hidden deep in
 461             ;;   the displayed string.
 462             ;;
 463             ;; - Because of `icomplete-prospects-height' , NAME may
 464             ;;   not even be displayed to the user.
 465             ;;
 466             ;; To circumvent all the above problems, provide a visual
 467             ;; cue to the user via an "empty string" in the try
 468             ;; completion field.
 469             (setq determ (concat open-bracket "" close-bracket)))
 470           ;; Compute prospects for display.
 471           (while (and comps (not limit))
 472             (setq comp
 473                   (if prefix-len (substring (car comps) prefix-len) (car comps))
 474                   comps (cdr comps))
 475             (setq prospects-len
 476                            (+ (string-width comp)
 477                               (string-width icomplete-separator)
 478                               prospects-len))
 479                      (if (< prospects-len prospects-max)
 480                          (push comp prospects)
 481               (setq limit t))))
 482         (setq prospects (nreverse prospects))
 483         ;; Decorate first of the prospects.
 484         (when prospects
 485           (let ((first (copy-sequence (pop prospects))))
 486             (put-text-property 0 (length first)
 487                                'face 'icomplete-first-match first)
 488             (push first prospects)))
 489         ;; Restore the base-size info, since completion-all-sorted-completions
 490         ;; is cached.
 491         (if last (setcdr last base-size))
 492         (if prospects
 493             (concat determ
 494                     "{"
 495                     (mapconcat 'identity prospects icomplete-separator)
 496                     (and limit (concat icomplete-separator ellipsis))
 497                     "}")
 498           (concat determ " [Matched]"))))))
 499
 500 ;;; Iswitchb compatibility
 501
 502 ;; We moved Iswitchb to `obsolete' in 24.4, but autoloads in files in
 503 ;; `obsolete' aren't obeyed (since that would encourage people to keep using
 504 ;; those packages, oblivious to their obsolescence).  Given the fact that
 505 ;; Iswitchb was very popular, we decided to keep its autoload for a bit longer,
 506 ;; so we moved it here.
 507
 508 ;;;###autoload(when (locate-library "obsolete/iswitchb")
 509 ;;;###autoload  (autoload 'iswitchb-mode "iswitchb" "Toggle Iswitchb mode." t)
 510 ;;;###autoload  (make-obsolete 'iswitchb-mode
 511 ;;;###autoload    "use `icomplete-mode' or `ido-mode' instead." "24.4"))
 512
 513 ;;;_* Provide
 514 (provide 'icomplete)
 515
 516 ;;_* Local emacs vars.
 517 ;;Local variables:
 518 ;;allout-layout: (-2 :)
 519 ;;End:
 520
 521 ;;; icomplete.el ends here