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]  'minibuffer-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-forward-completions ()
 159   "Step forward completions by one entry.
 160 Second entry becomes the first and can be selected with
 161 `minibuffer-force-complete-and-exit'."
 162   (interactive)
 163   (let* ((beg (icomplete--field-beg))
 164          (end (icomplete--field-end))
 165          (comps (completion-all-sorted-completions beg end))
 166          (last (last comps)))
 167     (when comps
 168       (setcdr last (cons (car comps) (cdr last)))
 169       (completion--cache-all-sorted-completions beg end (cdr comps)))))
 170
 171 (defun icomplete-backward-completions ()
 172   "Step backward completions by one entry.
 173 Last entry becomes the first and can be selected with
 174 `minibuffer-force-complete-and-exit'."
 175   (interactive)
 176   (let* ((beg (icomplete--field-beg))
 177          (end (icomplete--field-end))
 178          (comps (completion-all-sorted-completions beg end))
 179          (last-but-one (last comps 2))
 180          (last (cdr last-but-one)))
 181     (when (consp last)                ; At least two elements in comps
 182       (setcdr last-but-one (cdr last))
 183       (push (car last) comps)
 184       (completion--cache-all-sorted-completions beg end 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
 194 When this global minor mode is enabled, typing in the minibuffer
 195 continuously displays a list of possible completions that match
 196 the string you have typed.  See `icomplete-completions' for a
 197 description of how prospective completions are displayed.
 198
 199 For more information, see Info node `(emacs)Icomplete'.
 200 For options you can set, `\\[customize-group] icomplete'.
 201
 202 You can use the following key bindings to navigate and select
 203 completions:
 204
 205 \\{icomplete-minibuffer-map}"
 206   :global t :group 'icomplete
 207   (remove-hook 'minibuffer-setup-hook #'icomplete-minibuffer-setup)
 208   (remove-hook 'completion-in-region-mode-hook #'icomplete--in-region-setup)
 209   (when icomplete-mode
 210     (when icomplete-in-buffer
 211       (add-hook 'completion-in-region-mode-hook #'icomplete--in-region-setup))
 212     (add-hook 'minibuffer-setup-hook #'icomplete-minibuffer-setup)))
 213
 214 (defun icomplete--completion-table ()
 215   (if (window-minibuffer-p) minibuffer-completion-table
 216     (or (nth 2 completion-in-region--data)
 217         (message "In %S (w=%S): %S"
 218                  (current-buffer) (selected-window) (window-minibuffer-p)))))
 219 (defun icomplete--completion-predicate ()
 220   (if (window-minibuffer-p) minibuffer-completion-predicate
 221     (nth 3 completion-in-region--data)))
 222 (defun icomplete--field-string ()
 223   (if (window-minibuffer-p) (minibuffer-contents)
 224     (buffer-substring-no-properties
 225      (nth 0 completion-in-region--data)
 226      (nth 1 completion-in-region--data))))
 227 (defun icomplete--field-beg ()
 228   (if (window-minibuffer-p) (minibuffer-prompt-end)
 229     (nth 0 completion-in-region--data)))
 230 (defun icomplete--field-end ()
 231   (if (window-minibuffer-p) (point-max)
 232     (nth 1 completion-in-region--data)))
 233
 234 ;;;_ > icomplete-simple-completing-p ()
 235 (defun icomplete-simple-completing-p ()
 236   "Non-nil if current window is a minibuffer that's doing simple completion.
 237
 238 Conditions are:
 239    the selected window is a minibuffer,
 240    and not in the middle of macro execution,
 241    and the completion table is not a function (which would
 242        indicate some non-standard, non-simple completion mechanism,
 243        like file-name and other custom-func completions),
 244    and `icomplete-with-completion-tables' doesn't restrict completion."
 245
 246   (unless executing-kbd-macro
 247     (let ((table (icomplete--completion-table)))
 248       (and table
 249            (or (not (functionp table))
 250                (eq icomplete-with-completion-tables t)
 251                (member table icomplete-with-completion-tables))))))
 252
 253 ;;;_ > icomplete-minibuffer-setup ()
 254 (defun icomplete-minibuffer-setup ()
 255   "Run in minibuffer on activation to establish incremental completion.
 256 Usually run by inclusion in `minibuffer-setup-hook'."
 257   (when (and icomplete-mode (icomplete-simple-completing-p))
 258     (set (make-local-variable 'completion-show-inline-help) nil)
 259     (use-local-map (make-composed-keymap icomplete-minibuffer-map
 260                                          (current-local-map)))
 261     (add-hook 'pre-command-hook  #'icomplete-pre-command-hook  nil t)
 262     (add-hook 'post-command-hook #'icomplete-post-command-hook nil t)
 263     (run-hooks 'icomplete-minibuffer-setup-hook)
 264     (when icomplete-show-matches-on-no-input
 265       (icomplete-exhibit))))
 266
 267 (defvar icomplete--in-region-buffer nil)
 268
 269 (defun icomplete--in-region-setup ()
 270   (when (or (not completion-in-region-mode)
 271             (and icomplete--in-region-buffer
 272                  (not (eq icomplete--in-region-buffer (current-buffer)))))
 273     (with-current-buffer (or icomplete--in-region-buffer (current-buffer))
 274       (setq icomplete--in-region-buffer nil)
 275       (delete-overlay icomplete-overlay)
 276       (kill-local-variable 'completion-show-inline-help)
 277       (remove-hook 'pre-command-hook  'icomplete-pre-command-hook  t)
 278       (remove-hook 'post-command-hook 'icomplete-post-command-hook t)
 279       (message nil)))
 280   (when (and completion-in-region-mode
 281              icomplete-mode (icomplete-simple-completing-p))
 282     (setq icomplete--in-region-buffer (current-buffer))
 283     (set (make-local-variable 'completion-show-inline-help) nil)
 284     (let ((tem (assq 'completion-in-region-mode
 285                      minor-mode-overriding-map-alist)))
 286       (unless (memq icomplete-minibuffer-map (cdr tem))
 287         (setcdr tem (make-composed-keymap icomplete-minibuffer-map
 288                                           (cdr tem)))))
 289     (add-hook 'pre-command-hook  'icomplete-pre-command-hook  nil t)
 290     (add-hook 'post-command-hook 'icomplete-post-command-hook nil t)))
 291 \f
 292
 293
 294 ;;;_* Completion
 295
 296 ;;;_ > icomplete-tidy ()
 297 (defun icomplete-tidy ()
 298   "Remove completions display (if any) prior to new user input.
 299 Should be run in on the minibuffer `pre-command-hook'.
 300 See `icomplete-mode' and `minibuffer-setup-hook'."
 301   (delete-overlay icomplete-overlay))
 302
 303 ;;;_ > icomplete-exhibit ()
 304 (defun icomplete-exhibit ()
 305   "Insert Icomplete completions display.
 306 Should be run via minibuffer `post-command-hook'.
 307 See `icomplete-mode' and `minibuffer-setup-hook'."
 308   (when (and icomplete-mode
 309              (icomplete-simple-completing-p)) ;Shouldn't be necessary.
 310     (save-excursion
 311       (goto-char (point-max))
 312                                         ; Insert the match-status information:
 313       (if (and (or icomplete-show-matches-on-no-input
 314                    (> (icomplete--field-end) (icomplete--field-beg)))
 315                (or
 316                 ;; Don't bother with delay after certain number of chars:
 317                 (> (- (point) (icomplete--field-beg))
 318                    icomplete-max-delay-chars)
 319                 ;; Don't delay if the completions are known.
 320                 completion-all-sorted-completions
 321                 ;; Don't delay if alternatives number is small enough:
 322                 (and (sequencep (icomplete--completion-table))
 323                      (< (length (icomplete--completion-table))
 324                         icomplete-delay-completions-threshold))
 325                 ;; Delay - give some grace time for next keystroke, before
 326                 ;; embarking on computing completions:
 327                 (sit-for icomplete-compute-delay)))
 328           (let* ((field-string (icomplete--field-string))
 329                  (text (while-no-input
 330                          (icomplete-completions
 331                           field-string
 332                           (icomplete--completion-table)
 333                           (icomplete--completion-predicate)
 334                           (if (window-minibuffer-p)
 335                               (not minibuffer-completion-confirm)))))
 336                  (buffer-undo-list t)
 337                  deactivate-mark)
 338             ;; Do nothing if while-no-input was aborted.
 339             (when (stringp text)
 340               (move-overlay icomplete-overlay (point) (point) (current-buffer))
 341               ;; The current C cursor code doesn't know to use the overlay's
 342               ;; marker's stickiness to figure out whether to place the cursor
 343               ;; before or after the string, so let's spoon-feed it the pos.
 344               (put-text-property 0 1 'cursor t text)
 345               (overlay-put icomplete-overlay 'after-string text)))))))
 346
 347 ;;;_ > icomplete-completions (name candidates predicate require-match)
 348 (defun icomplete-completions (name candidates predicate require-match)
 349   "Identify prospective candidates for minibuffer completion.
 350
 351 The display is updated with each minibuffer keystroke during
 352 minibuffer completion.
 353
 354 Prospective completion suffixes (if any) are displayed, bracketed by
 355 one of (), [], or {} pairs.  The choice of brackets is as follows:
 356
 357   (...) - a single prospect is identified and matching is enforced,
 358   [...] - a single prospect is identified but matching is optional, or
 359   {...} - multiple prospects, separated by commas, are indicated, and
 360           further input is required to distinguish a single one.
 361
 362 If there are multiple possibilities, `icomplete-separator' separates them.
 363
 364 The displays for unambiguous matches have ` [Matched]' appended
 365 \(whether complete or not), or ` [No matches]', if no eligible
 366 matches exist."
 367   (let* ((minibuffer-completion-table candidates)
 368          (minibuffer-completion-predicate predicate)
 369          (md (completion--field-metadata (icomplete--field-beg)))
 370          (comps (completion-all-sorted-completions
 371                  (icomplete--field-beg) (icomplete--field-end)))
 372          (last (if (consp comps) (last comps)))
 373          (base-size (cdr last))
 374          (open-bracket (if require-match "(" "["))
 375          (close-bracket (if require-match ")" "]")))
 376     ;; `concat'/`mapconcat' is the slow part.
 377     (if (not (consp comps))
 378         (progn ;;(debug (format "Candidates=%S field=%S" candidates name))
 379                (format " %sNo matches%s" open-bracket close-bracket))
 380       (if last (setcdr last nil))
 381       (let* ((most-try
 382               (if (and base-size (> base-size 0))
 383                   (completion-try-completion
 384                    name candidates predicate (length name) md)
 385                 ;; If the `comps' are 0-based, the result should be
 386                 ;; the same with `comps'.
 387                 (completion-try-completion
 388                  name comps nil (length name) md)))
 389              (most (if (consp most-try) (car most-try)
 390                      (if most-try (car comps) "")))
 391              ;; Compare name and most, so we can determine if name is
 392              ;; a prefix of most, or something else.
 393              (compare (compare-strings name nil nil
 394                                        most nil nil completion-ignore-case))
 395              (ellipsis (if (char-displayable-p ?…) "…" "..."))
 396              (determ (unless (or (eq t compare) (eq t most-try)
 397                                  (= (setq compare (1- (abs compare)))
 398                                     (length most)))
 399                        (concat open-bracket
 400                                (cond
 401                                 ((= compare (length name))
 402                                  ;; Typical case: name is a prefix.
 403                                  (substring most compare))
 404                                 ;; Don't bother truncating if it doesn't gain
 405                                 ;; us at least 2 columns.
 406                                 ((< compare (+ 2 (string-width ellipsis))) most)
 407                                 (t (concat ellipsis (substring most compare))))
 408                                close-bracket)))
 409              ;;"-prospects" - more than one candidate
 410              (prospects-len (+ (string-width
 411                                 (or determ (concat open-bracket close-bracket)))
 412                                (string-width icomplete-separator)
 413                                (+ 2 (string-width ellipsis)) ;; take {…} into account
 414                                (string-width (buffer-string))))
 415              (prospects-max
 416               ;; Max total length to use, including the minibuffer content.
 417               (* (+ icomplete-prospects-height
 418                     ;; If the minibuffer content already uses up more than
 419                     ;; one line, increase the allowable space accordingly.
 420                     (/ prospects-len (window-width)))
 421                  (window-width)))
 422              ;; Find the common prefix among `comps'.
 423              ;; We can't use the optimization below because its assumptions
 424              ;; aren't always true, e.g. when completion-cycling (bug#10850):
 425              ;; (if (eq t (compare-strings (car comps) nil (length most)
 426              ;;                          most nil nil completion-ignore-case))
 427              ;;     ;; Common case.
 428              ;;     (length most)
 429              ;; Else, use try-completion.
 430              (prefix (when icomplete-hide-common-prefix
 431                        (try-completion "" comps)))
 432              (prefix-len
 433               (and (stringp prefix)
 434                    ;; Only hide the prefix if the corresponding info
 435                    ;; is already displayed via `most'.
 436                    (string-prefix-p prefix most t)
 437                    (length prefix))) ;;)
 438              prospects comp limit)
 439         (if (or (eq most-try t) (not (consp (cdr comps))))
 440             (setq prospects nil)
 441           (when (member name comps)
 442             ;; NAME is complete but not unique.  This scenario poses
 443             ;; following UI issues:
 444             ;;
 445             ;; - When `icomplete-hide-common-prefix' is non-nil, NAME
 446             ;;   is stripped empty.  This would make the entry
 447             ;;   inconspicuous.
 448             ;;
 449             ;; - Due to sorting of completions, NAME may not be the
 450             ;;   first of the prospects and could be hidden deep in
 451             ;;   the displayed string.
 452             ;;
 453             ;; - Because of `icomplete-prospects-height' , NAME may
 454             ;;   not even be displayed to the user.
 455             ;;
 456             ;; To circumvent all the above problems, provide a visual
 457             ;; cue to the user via an "empty string" in the try
 458             ;; completion field.
 459             (setq determ (concat open-bracket "" close-bracket)))
 460           ;; Compute prospects for display.
 461           (while (and comps (not limit))
 462             (setq comp
 463                   (if prefix-len (substring (car comps) prefix-len) (car comps))
 464                   comps (cdr comps))
 465             (setq prospects-len
 466                            (+ (string-width comp)
 467                               (string-width icomplete-separator)
 468                               prospects-len))
 469                      (if (< prospects-len prospects-max)
 470                          (push comp prospects)
 471               (setq limit t))))
 472         (setq prospects (nreverse prospects))
 473         ;; Decorate first of the prospects.
 474         (when prospects
 475           (let ((first (copy-sequence (pop prospects))))
 476             (put-text-property 0 (length first)
 477                                'face 'icomplete-first-match first)
 478             (push first prospects)))
 479         ;; Restore the base-size info, since completion-all-sorted-completions
 480         ;; is cached.
 481         (if last (setcdr last base-size))
 482         (if prospects
 483             (concat determ
 484                     "{"
 485                     (mapconcat 'identity prospects icomplete-separator)
 486                     (and limit (concat icomplete-separator ellipsis))
 487                     "}")
 488           (concat determ " [Matched]"))))))
 489
 490 ;;;_* Provide
 491 (provide 'icomplete)
 492
 493 ;;_* Local emacs vars.
 494 ;;Local variables:
 495 ;;allout-layout: (-2 :)
 496 ;;End:
 497
 498 ;;; icomplete.el ends here