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 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, or (at your option)
  17 ;; 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; see the file COPYING.  If not, write to the
  26 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  27 ;; Boston, MA 02110-1301, USA.
  28
  29 ;;; Commentary:
  30
  31 ;; Loading this package implements a more fine-grained minibuffer
  32 ;; completion feedback scheme.  Prospective completions are concisely
  33 ;; indicated within the minibuffer itself, with each successive
  34 ;; keystroke.
  35
  36 ;; See `icomplete-completions' docstring for a description of the
  37 ;; icomplete display format.
  38
  39 ;; See the `icomplete-minibuffer-setup-hook' docstring for a means to
  40 ;; customize icomplete setup for interoperation with other
  41 ;; minibuffer-oriented packages.
  42
  43 ;; To activate icomplete mode, load the package and use the
  44 ;; `icomplete-mode' function.  You can subsequently deactivate it by
  45 ;; invoking the function icomplete-mode with a negative prefix-arg
  46 ;; (C-U -1 ESC-x icomplete-mode).  Also, you can prevent activation of
  47 ;; the mode during package load by first setting the variable
  48 ;; `icomplete-mode' to nil.  Icompletion can be enabled any time after
  49 ;; the package is loaded by invoking icomplete-mode without a prefix
  50 ;; arg.
  51
  52 ;; Thanks to everyone for their suggestions for refinements of this
  53 ;; package.  I particularly have to credit Michael Cook, who
  54 ;; implemented an incremental completion style in his 'iswitch'
  55 ;; functions that served as a model for icomplete.  Some other
  56 ;; contributors: Noah Friedman (restructuring as minor mode), Colin
  57 ;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and others.
  58
  59 ;; klm.
  60
  61 ;;; Code:
  62
  63 ;;;_* Provide
  64 (provide 'icomplete)
  65
  66
  67 (defgroup icomplete nil
  68   "Show completions dynamically in minibuffer."
  69   :prefix "icomplete-"
  70   :group 'minibuffer)
  71
  72 ;;;_* User Customization variables
  73 (defcustom icomplete-prospects-length 80
  74   "*Length of string displaying the prospects."
  75   :type 'integer
  76   :group 'icomplete)
  77
  78 (defcustom icomplete-compute-delay .3
  79   "*Completions-computation stall, used only with large-number
  80 completions - see `icomplete-delay-completions-threshold'."
  81   :type 'number
  82   :group 'icomplete)
  83
  84 (defcustom icomplete-delay-completions-threshold 400
  85   "*Pending-completions number over which to apply icomplete-compute-delay."
  86   :type 'integer
  87   :group 'icomplete)
  88
  89 (defcustom icomplete-max-delay-chars 3
  90   "*Maximum number of initial chars to apply icomplete compute delay."
  91   :type 'integer
  92   :group 'icomplete)
  93
  94 (defcustom icomplete-show-key-bindings t
  95   "*If non-nil, show key bindings as well as completion for sole matches."
  96   :type 'boolean
  97   :group 'icomplete)
  98
  99 (defcustom icomplete-minibuffer-setup-hook nil
 100   "*Icomplete-specific customization of minibuffer setup.
 101
 102 This hook is run during minibuffer setup if icomplete is active.
 103 It is intended for use in customizing icomplete for interoperation
 104 with other features and packages.  For instance:
 105
 106   \(add-hook 'icomplete-minibuffer-setup-hook
 107             \(function
 108              \(lambda ()
 109                \(make-local-variable 'max-mini-window-height)
 110                \(setq max-mini-window-height 3))))
 111
 112 will constrain Emacs to a maximum minibuffer height of 3 lines when
 113 icompletion is occurring."
 114   :type 'hook
 115   :group 'icomplete)
 116
 117
 118 ;;;_* Initialization
 119
 120 ;;;_ + Internal Variables
 121 ;;;_  = icomplete-eoinput nil
 122 (defvar icomplete-eoinput nil
 123   "Point where minibuffer input ends and completion info begins.")
 124 (make-variable-buffer-local 'icomplete-eoinput)
 125 ;;;_  = icomplete-pre-command-hook
 126 (defvar icomplete-pre-command-hook nil
 127   "Incremental-minibuffer-completion pre-command-hook.
 128
 129 Is run in minibuffer before user input when `icomplete-mode' is non-nil.
 130 Use `icomplete-mode' function to set it up properly for incremental
 131 minibuffer completion.")
 132 (add-hook 'icomplete-pre-command-hook 'icomplete-tidy)
 133 ;;;_  = icomplete-post-command-hook
 134 (defvar icomplete-post-command-hook nil
 135   "Incremental-minibuffer-completion post-command-hook.
 136
 137 Is run in minibuffer after user input when `icomplete-mode' is non-nil.
 138 Use `icomplete-mode' function to set it up properly for incremental
 139 minibuffer completion.")
 140 (add-hook 'icomplete-post-command-hook 'icomplete-exhibit)
 141
 142 (defun icomplete-get-keys (func-name)
 143   "Return strings naming keys bound to `func-name', or nil if none.
 144 Examines the prior, not current, buffer, presuming that current buffer
 145 is minibuffer."
 146   (if (commandp func-name)
 147     (save-excursion
 148       (let* ((sym (intern func-name))
 149              (buf (other-buffer nil t))
 150              (map (save-excursion (set-buffer buf) (current-local-map)))
 151              (keys (where-is-internal sym map)))
 152         (if keys
 153             (concat "<"
 154                     (mapconcat 'key-description
 155                                (sort keys
 156                                      #'(lambda (x y)
 157                                          (< (length x) (length y))))
 158                                ", ")
 159                     ">"))))))
 160 ;;;_  = icomplete-with-completion-tables
 161 (defvar icomplete-with-completion-tables '(internal-complete-buffer)
 162   "Specialized completion tables with which icomplete should operate.
 163
 164 Icomplete does not operate with any specialized completion tables
 165 except those on this list.")
 166
 167 ;;;_ > icomplete-mode (&optional prefix)
 168 ;;;###autoload
 169 (define-minor-mode icomplete-mode
 170   "Toggle incremental minibuffer completion for this Emacs session.
 171 With a numeric argument, turn Icomplete mode on if ARG is positive,
 172 otherwise turn it off."
 173   :global t :group 'icomplete
 174   (if icomplete-mode
 175       ;; The following is not really necessary after first time -
 176       ;; no great loss.
 177       (add-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup)
 178     (remove-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup)))
 179
 180 ;;;_ > icomplete-simple-completing-p ()
 181 (defun icomplete-simple-completing-p ()
 182   "Non-nil if current window is minibuffer that's doing simple completion.
 183
 184 Conditions are:
 185    the selected window is a minibuffer,
 186    and not in the middle of macro execution,
 187    and `minibuffer-completion-table' is not a symbol (which would
 188        indicate some non-standard, non-simple completion mechanism,
 189        like file-name and other custom-func completions)."
 190
 191   (and (window-minibuffer-p (selected-window))
 192        (not executing-kbd-macro)
 193        minibuffer-completion-table
 194        (or (not (functionp minibuffer-completion-table))
 195            (member minibuffer-completion-table
 196                    icomplete-with-completion-tables))))
 197
 198 ;;;_ > icomplete-minibuffer-setup ()
 199 (defun icomplete-minibuffer-setup ()
 200   "Run in minibuffer on activation to establish incremental completion.
 201 Usually run by inclusion in `minibuffer-setup-hook'."
 202   (when (and icomplete-mode (icomplete-simple-completing-p))
 203     (add-hook 'pre-command-hook
 204               (lambda () (run-hooks 'icomplete-pre-command-hook))
 205               nil t)
 206     (add-hook 'post-command-hook
 207               (lambda () (run-hooks 'icomplete-post-command-hook))
 208               nil t)
 209     (run-hooks 'icomplete-minibuffer-setup-hook)))
 210 ;\f
 211
 212
 213 ;;;_* Completion
 214
 215 ;;;_ > icomplete-tidy ()
 216 (defun icomplete-tidy ()
 217   "Remove completions display \(if any) prior to new user input.
 218 Should be run in on the minibuffer `pre-command-hook'.  See `icomplete-mode'
 219 and `minibuffer-setup-hook'."
 220   (when (and icomplete-mode icomplete-eoinput)
 221
 222     (unless (>= icomplete-eoinput (point-max))
 223       (let ((buffer-undo-list t) ; prevent entry
 224             deactivate-mark)
 225         (delete-region icomplete-eoinput (point-max))))
 226
 227     ;; Reestablish the safe value.
 228     (setq icomplete-eoinput nil)))
 229
 230 ;;;_ > icomplete-exhibit ()
 231 (defun icomplete-exhibit ()
 232   "Insert icomplete completions display.
 233 Should be run via minibuffer `post-command-hook'.  See `icomplete-mode'
 234 and `minibuffer-setup-hook'."
 235   (when (and icomplete-mode (icomplete-simple-completing-p))
 236     (save-excursion
 237       (goto-char (point-max))
 238       ;; Register the end of input, so we know where the extra stuff
 239       ;; (match-status info) begins:
 240       (setq icomplete-eoinput (point))
 241                                         ; Insert the match-status information:
 242       (if (and (> (point-max) (minibuffer-prompt-end))
 243                buffer-undo-list         ; Wait for some user input.
 244                (or
 245                 ;; Don't bother with delay after certain number of chars:
 246                 (> (- (point) (field-beginning)) icomplete-max-delay-chars)
 247                 ;; Don't delay if alternatives number is small enough:
 248                 (and (sequencep minibuffer-completion-table)
 249                      (< (length minibuffer-completion-table)
 250                         icomplete-delay-completions-threshold))
 251                 ;; Delay - give some grace time for next keystroke, before
 252                 ;; embarking on computing completions:
 253                 (sit-for icomplete-compute-delay)))
 254           (let ((text (while-no-input
 255                         (list
 256                          (icomplete-completions
 257                           (field-string)
 258                           minibuffer-completion-table
 259                           minibuffer-completion-predicate
 260                           (not minibuffer-completion-confirm)))))
 261                 (buffer-undo-list t)
 262                 deactivate-mark)
 263             ;; Do nothing if while-no-input was aborted.
 264             (if (consp text) (insert (car 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   ;; 'all-completions' doesn't like empty
 287   ;; minibuffer-completion-table's (ie: (nil))
 288   (if (and (listp candidates) (null (car candidates)))
 289       (setq candidates nil))
 290
 291   (let ((comps (all-completions name candidates predicate))
 292                                         ; "-determined" - only one candidate
 293         (open-bracket-determined (if require-match "(" "["))
 294         (close-bracket-determined (if require-match ")" "]")))
 295     ;; `concat'/`mapconcat' is the slow part.  With the introduction of
 296     ;; `icomplete-prospects-length', there is no need for `catch'/`throw'.
 297     (if (null comps) (format " %sNo matches%s"
 298                              open-bracket-determined
 299                              close-bracket-determined)
 300       (let* ((most-try (try-completion name (mapcar (function list) comps)))
 301              (most (if (stringp most-try) most-try (car comps)))
 302              (most-len (length most))
 303              (determ (and (> most-len (length name))
 304                           (concat open-bracket-determined
 305                                   (substring most (length name))
 306                                   close-bracket-determined)))
 307              ;;"-prospects" - more than one candidate
 308              (prospects-len 0)
 309              prospects most-is-exact comp)
 310         (if (eq most-try t)
 311             (setq prospects nil)
 312           (while (and comps (< prospects-len icomplete-prospects-length))
 313             (setq comp (substring (car comps) most-len)
 314                   comps (cdr comps))
 315             (cond ((string-equal comp "") (setq most-is-exact t))
 316                   ((member comp prospects))
 317                   (t (setq prospects (cons comp prospects)
 318                            prospects-len (+ (length comp) 1 prospects-len))))))
 319         (if prospects
 320             (concat determ
 321                     "{"
 322                     (and most-is-exact ",")
 323                     (mapconcat 'identity
 324                                (sort prospects (function string-lessp))
 325                                ",")
 326                     (and comps ",...")
 327                     "}")
 328           (concat determ
 329                   " [Matched"
 330                   (let ((keys (and icomplete-show-key-bindings
 331                                    (commandp (intern-soft most))
 332                                    (icomplete-get-keys most))))
 333                     (if keys (concat "; " keys) ""))
 334                   "]"))))))
 335
 336 ;;;_* Local emacs vars.
 337 ;;;Local variables:
 338 ;;;allout-layout: (-2 :)
 339 ;;;End:
 340
 341 ;; arch-tag: 339ec25a-0741-4eb6-be63-997532e89b0f
 342 ;;; icomplete.el ends here