lisp/icomplete.el

   1 ;;; icomplete.el --- minibuffer completion incremental feedback
   2
   3 ;; Copyright (C) 1992-1994, 1997, 1999, 2001-2011 Free Software Foundation, Inc.
   4
   5 ;; Author: Ken Manheimer <klm@i.am>
   6 ;; Maintainer: Ken Manheimer <klm@i.am>
   7 ;; Created: Mar 1993 Ken Manheimer, klm@nist.gov - first release to usenet
   8 ;; Last update: Ken Manheimer <klm@i.am>, 11/18/1999.
   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 ;; Loading 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 activate icomplete mode, load the package and use the
  41 ;; `icomplete-mode' function.  You can subsequently deactivate it by
  42 ;; invoking the function icomplete-mode with a negative prefix-arg
  43 ;; (C-U -1 ESC-x icomplete-mode).  Also, you can prevent activation of
  44 ;; the mode during package load by first setting the variable
  45 ;; `icomplete-mode' to nil.  Icompletion can be enabled any time after
  46 ;; the package is loaded by invoking icomplete-mode without a prefix
  47 ;; arg.
  48
  49 ;; Thanks to everyone for their suggestions for refinements of this
  50 ;; package.  I particularly have to credit Michael Cook, who
  51 ;; implemented an incremental completion style in his 'iswitch'
  52 ;; functions that served as a model for icomplete.  Some other
  53 ;; contributors: Noah Friedman (restructuring as minor mode), Colin
  54 ;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and others.
  55
  56 ;; klm.
  57
  58 ;;; Code:
  59
  60 ;;;_* Provide
  61 (provide 'icomplete)
  62
  63
  64 (defgroup icomplete nil
  65   "Show completions dynamically in minibuffer."
  66   :prefix "icomplete-"
  67   :group 'minibuffer)
  68
  69 (defvar icomplete-prospects-length 80)
  70 (make-obsolete-variable
  71  'icomplete-prospects-length 'icomplete-prospects-height "23.1")
  72
  73 ;;;_* User Customization variables
  74 (defcustom icomplete-prospects-height
  75   ;; 20 is an estimated common size for the prompt + minibuffer content, to
  76   ;; try to guess the number of lines used up by icomplete-prospects-length.
  77   (+ 1 (/ (+ icomplete-prospects-length 20) (window-width)))
  78   "Maximum number of lines to use in the minibuffer."
  79   :type 'integer
  80   :group 'icomplete
  81   :version "23.1")
  82
  83 (defcustom icomplete-compute-delay .3
  84   "Completions-computation stall, used only with large-number completions.
  85 See `icomplete-delay-completions-threshold'."
  86   :type 'number
  87   :group 'icomplete)
  88
  89 (defcustom icomplete-delay-completions-threshold 400
  90   "Pending-completions number over which to apply `icomplete-compute-delay'."
  91   :type 'integer
  92   :group 'icomplete)
  93
  94 (defcustom icomplete-max-delay-chars 3
  95   "Maximum number of initial chars to apply icomplete compute delay."
  96   :type 'integer
  97   :group 'icomplete)
  98
  99 (defcustom icomplete-show-key-bindings t
 100   "If non-nil, show key bindings as well as completion for sole matches."
 101   :type 'boolean
 102   :group 'icomplete)
 103
 104 (defcustom icomplete-minibuffer-setup-hook nil
 105   "Icomplete-specific customization of minibuffer setup.
 106
 107 This hook is run during minibuffer setup if icomplete is active.
 108 It is intended for use in customizing icomplete for interoperation
 109 with other features and packages.  For instance:
 110
 111   \(add-hook 'icomplete-minibuffer-setup-hook
 112             \(function
 113              \(lambda ()
 114                \(make-local-variable 'max-mini-window-height)
 115                \(setq max-mini-window-height 3))))
 116
 117 will constrain Emacs to a maximum minibuffer height of 3 lines when
 118 icompletion is occurring."
 119   :type 'hook
 120   :group 'icomplete)
 121
 122
 123 ;;;_* Initialization
 124
 125 ;;;_ + Internal Variables
 126 ;;;_  = icomplete-eoinput nil
 127 (defvar icomplete-overlay (make-overlay (point-min) (point-min) nil t t)
 128   "Overlay used to display the list of completions.")
 129
 130 ;;;_  = icomplete-pre-command-hook
 131 (defvar icomplete-pre-command-hook nil
 132   "Incremental-minibuffer-completion pre-command-hook.
 133
 134 Is run in minibuffer before user input when `icomplete-mode' is non-nil.
 135 Use `icomplete-mode' function to set it up properly for incremental
 136 minibuffer completion.")
 137 (add-hook 'icomplete-pre-command-hook 'icomplete-tidy)
 138 ;;;_  = icomplete-post-command-hook
 139 (defvar icomplete-post-command-hook nil
 140   "Incremental-minibuffer-completion post-command-hook.
 141
 142 Is run in minibuffer after user input when `icomplete-mode' is non-nil.
 143 Use `icomplete-mode' function to set it up properly for incremental
 144 minibuffer completion.")
 145 (add-hook 'icomplete-post-command-hook 'icomplete-exhibit)
 146
 147 (defun icomplete-get-keys (func-name)
 148   "Return strings naming keys bound to FUNC-NAME, or nil if none.
 149 Examines the prior, not current, buffer, presuming that current buffer
 150 is minibuffer."
 151   (when (commandp func-name)
 152     (save-excursion
 153       (let* ((sym (intern func-name))
 154              (buf (other-buffer nil t))
 155              (keys (with-current-buffer buf (where-is-internal sym))))
 156         (when keys
 157           (concat "<"
 158                   (mapconcat 'key-description
 159                              (sort keys
 160                                    #'(lambda (x y)
 161                                        (< (length x) (length y))))
 162                              ", ")
 163                   ">"))))))
 164 ;;;_  = icomplete-with-completion-tables
 165 (defvar icomplete-with-completion-tables '(internal-complete-buffer)
 166   "Specialized completion tables with which icomplete should operate.
 167
 168 Icomplete does not operate with any specialized completion tables
 169 except those on this list.")
 170
 171 ;;;_ > icomplete-mode (&optional prefix)
 172 ;;;###autoload
 173 (define-minor-mode icomplete-mode
 174   "Toggle incremental minibuffer completion for this Emacs session.
 175 With a numeric argument, turn Icomplete mode on if ARG is positive,
 176 otherwise turn it off."
 177   :global t :group 'icomplete
 178   (if icomplete-mode
 179       ;; The following is not really necessary after first time -
 180       ;; no great loss.
 181       (add-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup)
 182     (remove-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup)))
 183
 184 ;;;_ > icomplete-simple-completing-p ()
 185 (defun icomplete-simple-completing-p ()
 186   "Non-nil if current window is minibuffer that's doing simple completion.
 187
 188 Conditions are:
 189    the selected window is a minibuffer,
 190    and not in the middle of macro execution,
 191    and `minibuffer-completion-table' is not a symbol (which would
 192        indicate some non-standard, non-simple completion mechanism,
 193        like file-name and other custom-func completions)."
 194
 195   (and (window-minibuffer-p (selected-window))
 196        (not executing-kbd-macro)
 197        minibuffer-completion-table
 198        (or (not (functionp minibuffer-completion-table))
 199            (eq icomplete-with-completion-tables t)
 200            (member minibuffer-completion-table
 201                    icomplete-with-completion-tables))))
 202
 203 ;;;_ > icomplete-minibuffer-setup ()
 204 (defun icomplete-minibuffer-setup ()
 205   "Run in minibuffer on activation to establish incremental completion.
 206 Usually run by inclusion in `minibuffer-setup-hook'."
 207   (when (and icomplete-mode (icomplete-simple-completing-p))
 208     (add-hook 'pre-command-hook
 209               (lambda () (run-hooks 'icomplete-pre-command-hook))
 210               nil t)
 211     (add-hook 'post-command-hook
 212               (lambda () (run-hooks 'icomplete-post-command-hook))
 213               nil t)
 214     (run-hooks 'icomplete-minibuffer-setup-hook)))
 215 ;\f
 216
 217
 218 ;;;_* Completion
 219
 220 ;;;_ > icomplete-tidy ()
 221 (defun icomplete-tidy ()
 222   "Remove completions display \(if any) prior to new user input.
 223 Should be run in on the minibuffer `pre-command-hook'.  See `icomplete-mode'
 224 and `minibuffer-setup-hook'."
 225   (delete-overlay icomplete-overlay))
 226
 227 ;;;_ > icomplete-exhibit ()
 228 (defun icomplete-exhibit ()
 229   "Insert icomplete completions display.
 230 Should be run via minibuffer `post-command-hook'.  See `icomplete-mode'
 231 and `minibuffer-setup-hook'."
 232   (when (and icomplete-mode (icomplete-simple-completing-p))
 233     (save-excursion
 234       (goto-char (point-max))
 235                                         ; Insert the match-status information:
 236       (if (and (> (point-max) (minibuffer-prompt-end))
 237                buffer-undo-list         ; Wait for some user input.
 238                (or
 239                 ;; Don't bother with delay after certain number of chars:
 240                 (> (- (point) (field-beginning)) icomplete-max-delay-chars)
 241                 ;; Don't delay if alternatives number is small enough:
 242                 (and (sequencep minibuffer-completion-table)
 243                      (< (length minibuffer-completion-table)
 244                         icomplete-delay-completions-threshold))
 245                 ;; Delay - give some grace time for next keystroke, before
 246                 ;; embarking on computing completions:
 247                 (sit-for icomplete-compute-delay)))
 248           (let ((text (while-no-input
 249                          (icomplete-completions
 250                           (field-string)
 251                           minibuffer-completion-table
 252                           minibuffer-completion-predicate
 253                          (not minibuffer-completion-confirm))))
 254                 (buffer-undo-list t)
 255                 deactivate-mark)
 256             ;; Do nothing if while-no-input was aborted.
 257             (when (stringp text)
 258               (move-overlay icomplete-overlay (point) (point) (current-buffer))
 259               ;; The current C cursor code doesn't know to use the overlay's
 260               ;; marker's stickiness to figure out whether to place the cursor
 261               ;; before or after the string, so let's spoon-feed it the pos.
 262               (put-text-property 0 1 'cursor t text)
 263               (overlay-put icomplete-overlay 'after-string text)))))))
 264
 265 ;;;_ > icomplete-completions (name candidates predicate require-match)
 266 (defun icomplete-completions (name candidates predicate require-match)
 267   "Identify prospective candidates for minibuffer completion.
 268
 269 The display is updated with each minibuffer keystroke during
 270 minibuffer completion.
 271
 272 Prospective completion suffixes (if any) are displayed, bracketed by
 273 one of \(), \[], or \{} pairs.  The choice of brackets is as follows:
 274
 275   \(...) - a single prospect is identified and matching is enforced,
 276   \[...] - a single prospect is identified but matching is optional, or
 277   \{...} - multiple prospects, separated by commas, are indicated, and
 278           further input is required to distinguish a single one.
 279
 280 The displays for unambiguous matches have ` [Matched]' appended
 281 \(whether complete or not), or ` \[No matches]', if no eligible
 282 matches exist.  \(Keybindings for uniquely matched commands
 283 are exhibited within the square braces.)"
 284
 285   (let* ((non-essential t)
 286          (comps (completion-all-sorted-completions))
 287          (last (if (consp comps) (last comps)))
 288          (base-size (cdr last))
 289          (open-bracket (if require-match "(" "["))
 290          (close-bracket (if require-match ")" "]")))
 291     ;; `concat'/`mapconcat' is the slow part.
 292     (if (not (consp comps))
 293         (format " %sNo matches%s" open-bracket close-bracket)
 294       (if last (setcdr last nil))
 295       (let* ((most-try
 296               (if (and base-size (> base-size 0))
 297                   (completion-try-completion
 298                    name candidates predicate (length name))
 299                 ;; If the `comps' are 0-based, the result should be
 300                 ;; the same with `comps'.
 301                 (completion-try-completion
 302                  name comps nil (length name))))
 303              (most (if (consp most-try) (car most-try)
 304                      (if most-try (car comps) "")))
 305              ;; Compare name and most, so we can determine if name is
 306              ;; a prefix of most, or something else.
 307              (compare (compare-strings name nil nil
 308                                        most nil nil completion-ignore-case))
 309              (determ (unless (or (eq t compare) (eq t most-try)
 310                                  (= (setq compare (1- (abs compare)))
 311                                     (length most)))
 312                        (concat open-bracket
 313                                (cond
 314                                 ((= compare (length name))
 315                                  ;; Typical case: name is a prefix.
 316                                  (substring most compare))
 317                                 ((< compare 5) most)
 318                                 (t (concat "..." (substring most compare))))
 319                                close-bracket)))
 320              ;;"-prospects" - more than one candidate
 321              (prospects-len (+ (length determ) 6 ;; take {,...} into account
 322                                (string-width (buffer-string))))
 323              (prospects-max
 324               ;; Max total length to use, including the minibuffer content.
 325               (* (+ icomplete-prospects-height
 326                     ;; If the minibuffer content already uses up more than
 327                     ;; one line, increase the allowable space accordingly.
 328                     (/ prospects-len (window-width)))
 329                  (window-width)))
 330              (prefix-len
 331               ;; Find the common prefix among `comps'.
 332               (if (eq t (compare-strings (car comps) nil (length most)
 333                                          most nil nil completion-ignore-case))
 334                   ;; Common case.
 335                   (length most)
 336                 ;; Else, use try-completion.
 337                 (let ((comps-prefix (try-completion "" comps)))
 338                   (and (stringp comps-prefix)
 339                        (length comps-prefix)))))
 340
 341              prospects most-is-exact comp limit)
 342         (if (eq most-try t) ;; (or (null (cdr comps))
 343             (setq prospects nil)
 344           (while (and comps (not limit))
 345             (setq comp
 346                   (if prefix-len (substring (car comps) prefix-len) (car comps))
 347                   comps (cdr comps))
 348             (cond ((string-equal comp "") (setq most-is-exact t))
 349                   ((member comp prospects))
 350                   (t (setq prospects-len
 351                            (+ (string-width comp) 1 prospects-len))
 352                      (if (< prospects-len prospects-max)
 353                          (push comp prospects)
 354                        (setq limit t))))))
 355         ;; Restore the base-size info, since completion-all-sorted-completions
 356         ;; is cached.
 357         (if last (setcdr last base-size))
 358         (if prospects
 359             (concat determ
 360                     "{"
 361                     (and most-is-exact ",")
 362                     (mapconcat 'identity (nreverse prospects) ",")
 363                     (and limit ",...")
 364                     "}")
 365           (concat determ
 366                   " [Matched"
 367                   (let ((keys (and icomplete-show-key-bindings
 368                                    (commandp (intern-soft most))
 369                                    (icomplete-get-keys most))))
 370                     (if keys (concat "; " keys) ""))
 371                   "]"))))))
 372
 373 ;;_* Local emacs vars.
 374 ;;Local variables:
 375 ;;allout-layout: (-2 :)
 376 ;;End:
 377
 378 ;;; icomplete.el ends here