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 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 ;;;_* User Customization variables
  71 (defcustom icomplete-prospects-length 80
  72   "Length of string displaying the prospects."
  73   :type 'integer
  74   :group 'icomplete)
  75
  76 (defcustom icomplete-compute-delay .3
  77   "Completions-computation stall, used only with large-number completions.
  78 See `icomplete-delay-completions-threshold'."
  79   :type 'number
  80   :group 'icomplete)
  81
  82 (defcustom icomplete-delay-completions-threshold 400
  83   "Pending-completions number over which to apply `icomplete-compute-delay'."
  84   :type 'integer
  85   :group 'icomplete)
  86
  87 (defcustom icomplete-max-delay-chars 3
  88   "Maximum number of initial chars to apply icomplete compute delay."
  89   :type 'integer
  90   :group 'icomplete)
  91
  92 (defcustom icomplete-show-key-bindings t
  93   "If non-nil, show key bindings as well as completion for sole matches."
  94   :type 'boolean
  95   :group 'icomplete)
  96
  97 (defcustom icomplete-minibuffer-setup-hook nil
  98   "Icomplete-specific customization of minibuffer setup.
  99
 100 This hook is run during minibuffer setup if icomplete is active.
 101 It is intended for use in customizing icomplete for interoperation
 102 with other features and packages.  For instance:
 103
 104   \(add-hook 'icomplete-minibuffer-setup-hook
 105             \(function
 106              \(lambda ()
 107                \(make-local-variable 'max-mini-window-height)
 108                \(setq max-mini-window-height 3))))
 109
 110 will constrain Emacs to a maximum minibuffer height of 3 lines when
 111 icompletion is occurring."
 112   :type 'hook
 113   :group 'icomplete)
 114
 115
 116 ;;;_* Initialization
 117
 118 ;;;_ + Internal Variables
 119 ;;;_  = icomplete-eoinput nil
 120 (defvar icomplete-eoinput nil
 121   "Point where minibuffer input ends and completion info begins.")
 122 (make-variable-buffer-local 'icomplete-eoinput)
 123 ;;;_  = icomplete-pre-command-hook
 124 (defvar icomplete-pre-command-hook nil
 125   "Incremental-minibuffer-completion pre-command-hook.
 126
 127 Is run in minibuffer before user input when `icomplete-mode' is non-nil.
 128 Use `icomplete-mode' function to set it up properly for incremental
 129 minibuffer completion.")
 130 (add-hook 'icomplete-pre-command-hook 'icomplete-tidy)
 131 ;;;_  = icomplete-post-command-hook
 132 (defvar icomplete-post-command-hook nil
 133   "Incremental-minibuffer-completion post-command-hook.
 134
 135 Is run in minibuffer after 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-post-command-hook 'icomplete-exhibit)
 139
 140 (defun icomplete-get-keys (func-name)
 141   "Return strings naming keys bound to `func-name', or nil if none.
 142 Examines the prior, not current, buffer, presuming that current buffer
 143 is minibuffer."
 144   (if (commandp func-name)
 145     (save-excursion
 146       (let* ((sym (intern func-name))
 147              (buf (other-buffer nil t))
 148              (keys (with-current-buffer buf (where-is-internal sym))))
 149         (if keys
 150             (concat "<"
 151                     (mapconcat 'key-description
 152                                (sort keys
 153                                      #'(lambda (x y)
 154                                          (< (length x) (length y))))
 155                                ", ")
 156                     ">"))))))
 157 ;;;_  = icomplete-with-completion-tables
 158 (defvar icomplete-with-completion-tables '(internal-complete-buffer)
 159   "Specialized completion tables with which icomplete should operate.
 160
 161 Icomplete does not operate with any specialized completion tables
 162 except those on this list.")
 163
 164 ;;;_ > icomplete-mode (&optional prefix)
 165 ;;;###autoload
 166 (define-minor-mode icomplete-mode
 167   "Toggle incremental minibuffer completion for this Emacs session.
 168 With a numeric argument, turn Icomplete mode on if ARG is positive,
 169 otherwise turn it off."
 170   :global t :group 'icomplete
 171   (if icomplete-mode
 172       ;; The following is not really necessary after first time -
 173       ;; no great loss.
 174       (add-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup)
 175     (remove-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup)))
 176
 177 ;;;_ > icomplete-simple-completing-p ()
 178 (defun icomplete-simple-completing-p ()
 179   "Non-nil if current window is minibuffer that's doing simple completion.
 180
 181 Conditions are:
 182    the selected window is a minibuffer,
 183    and not in the middle of macro execution,
 184    and `minibuffer-completion-table' is not a symbol (which would
 185        indicate some non-standard, non-simple completion mechanism,
 186        like file-name and other custom-func completions)."
 187
 188   (and (window-minibuffer-p (selected-window))
 189        (not executing-kbd-macro)
 190        minibuffer-completion-table
 191        (or (not (functionp minibuffer-completion-table))
 192            (member minibuffer-completion-table
 193                    icomplete-with-completion-tables))))
 194
 195 ;;;_ > icomplete-minibuffer-setup ()
 196 (defun icomplete-minibuffer-setup ()
 197   "Run in minibuffer on activation to establish incremental completion.
 198 Usually run by inclusion in `minibuffer-setup-hook'."
 199   (when (and icomplete-mode (icomplete-simple-completing-p))
 200     (add-hook 'pre-command-hook
 201               (lambda () (run-hooks 'icomplete-pre-command-hook))
 202               nil t)
 203     (add-hook 'post-command-hook
 204               (lambda () (run-hooks 'icomplete-post-command-hook))
 205               nil t)
 206     (run-hooks 'icomplete-minibuffer-setup-hook)))
 207 ;\f
 208
 209
 210 ;;;_* Completion
 211
 212 ;;;_ > icomplete-tidy ()
 213 (defun icomplete-tidy ()
 214   "Remove completions display \(if any) prior to new user input.
 215 Should be run in on the minibuffer `pre-command-hook'.  See `icomplete-mode'
 216 and `minibuffer-setup-hook'."
 217   (when (and icomplete-mode icomplete-eoinput)
 218
 219     (unless (>= icomplete-eoinput (point-max))
 220       (let ((buffer-undo-list t) ; prevent entry
 221             deactivate-mark)
 222         (delete-region icomplete-eoinput (point-max))))
 223
 224     ;; Reestablish the safe value.
 225     (setq icomplete-eoinput nil)))
 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       ;; Register the end of input, so we know where the extra stuff
 236       ;; (match-status info) begins:
 237       (setq icomplete-eoinput (point))
 238                                         ; Insert the match-status information:
 239       (if (and (> (point-max) (minibuffer-prompt-end))
 240                buffer-undo-list         ; Wait for some user input.
 241                (or
 242                 ;; Don't bother with delay after certain number of chars:
 243                 (> (- (point) (field-beginning)) icomplete-max-delay-chars)
 244                 ;; Don't delay if alternatives number is small enough:
 245                 (and (sequencep minibuffer-completion-table)
 246                      (< (length minibuffer-completion-table)
 247                         icomplete-delay-completions-threshold))
 248                 ;; Delay - give some grace time for next keystroke, before
 249                 ;; embarking on computing completions:
 250                 (sit-for icomplete-compute-delay)))
 251           (let ((text (while-no-input
 252                         (list
 253                          (icomplete-completions
 254                           (field-string)
 255                           minibuffer-completion-table
 256                           minibuffer-completion-predicate
 257                           (not minibuffer-completion-confirm)))))
 258                 (buffer-undo-list t)
 259                 deactivate-mark)
 260             ;; Do nothing if while-no-input was aborted.
 261             (if (consp text) (insert (car text))))))))
 262
 263 ;;;_ > icomplete-completions (name candidates predicate require-match)
 264 (defun icomplete-completions (name candidates predicate require-match)
 265   "Identify prospective candidates for minibuffer completion.
 266
 267 The display is updated with each minibuffer keystroke during
 268 minibuffer completion.
 269
 270 Prospective completion suffixes (if any) are displayed, bracketed by
 271 one of \(), \[], or \{} pairs.  The choice of brackets is as follows:
 272
 273   \(...) - a single prospect is identified and matching is enforced,
 274   \[...] - a single prospect is identified but matching is optional, or
 275   \{...} - multiple prospects, separated by commas, are indicated, and
 276           further input is required to distinguish a single one.
 277
 278 The displays for unambiguous matches have ` [Matched]' appended
 279 \(whether complete or not), or ` \[No matches]', if no eligible
 280 matches exist.  \(Keybindings for uniquely matched commands
 281 are exhibited within the square braces.)"
 282
 283   (let ((comps (all-completions name candidates predicate))
 284                                         ; "-determined" - only one candidate
 285         (open-bracket-determined (if require-match "(" "["))
 286         (close-bracket-determined (if require-match ")" "]")))
 287     ;; `concat'/`mapconcat' is the slow part.  With the introduction of
 288     ;; `icomplete-prospects-length', there is no need for `catch'/`throw'.
 289     (if (null comps) (format " %sNo matches%s"
 290                              open-bracket-determined
 291                              close-bracket-determined)
 292       (let* ((most-try (try-completion name (mapcar (function list) comps)))
 293              (most (if (stringp most-try) most-try (car comps)))
 294              (most-len (length most))
 295              (determ (and (> most-len (length name))
 296                           (concat open-bracket-determined
 297                                   (substring most (length name))
 298                                   close-bracket-determined)))
 299              ;;"-prospects" - more than one candidate
 300              (prospects-len (+ (length determ) 6)) ;; take {,...} into account
 301              prospects most-is-exact comp limit)
 302         (if (eq most-try t)
 303             (setq prospects nil)
 304           (while (and comps (not limit))
 305             (setq comp (substring (car comps) most-len)
 306                   comps (cdr comps))
 307             (cond ((string-equal comp "") (setq most-is-exact t))
 308                   ((member comp prospects))
 309                   (t (setq prospects-len (+ (length comp) 1 prospects-len))
 310                      (if (< prospects-len icomplete-prospects-length)
 311                          (setq prospects (cons comp prospects))
 312                        (setq limit t))))))
 313         (if prospects
 314             (concat determ
 315                     "{"
 316                     (and most-is-exact ",")
 317                     (mapconcat 'identity
 318                                (sort prospects (function string-lessp))
 319                                ",")
 320                     (and comps ",...")
 321                     "}")
 322           (concat determ
 323                   " [Matched"
 324                   (let ((keys (and icomplete-show-key-bindings
 325                                    (commandp (intern-soft most))
 326                                    (icomplete-get-keys most))))
 327                     (if keys (concat "; " keys) ""))
 328                   "]"))))))
 329
 330 ;;;_* Local emacs vars.
 331 ;;;Local variables:
 332 ;;;allout-layout: (-2 :)
 333 ;;;End:
 334
 335 ;; arch-tag: 339ec25a-0741-4eb6-be63-997532e89b0f
 336 ;;; icomplete.el ends here