lisp/icomplete.el

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