lisp/icomplete.el

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