lisp/icomplete.el

   1 ;;; icomplete.el --- minibuffer completion incremental feedback
   2
   3 ;; Copyright (C) 1992, 1993, 1994, 1997, 1999 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 2, or (at your option)
  16 ;; 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; see the file COPYING.  If not, write to the
  25 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  26 ;; Boston, MA 02111-1307, USA.
  27
  28 ;;; Commentary:
  29
  30 ;; Loading this package implements a more fine-grained minibuffer
  31 ;; completion feedback scheme.  Prospective completions are concisely
  32 ;; indicated within the minibuffer itself, with each successive
  33 ;; keystroke.
  34
  35 ;; See `icomplete-completions' docstring for a description of the
  36 ;; icomplete display format.
  37
  38 ;; See the `icomplete-minibuffer-setup-hook' docstring for a means to
  39 ;; customize icomplete setup for interoperation with other
  40 ;; minibuffer-oriented packages.
  41
  42 ;; To activate icomplete mode, load the package and use the
  43 ;; `icomplete-mode' function.  You can subsequently deactivate it by
  44 ;; invoking the function icomplete-mode with a negative prefix-arg
  45 ;; (C-U -1 ESC-x icomplete-mode).  Also, you can prevent activation of
  46 ;; the mode during package load by first setting the variable
  47 ;; `icomplete-mode' to nil.  Icompletion can be enabled any time after
  48 ;; the package is loaded by invoking icomplete-mode without a prefix
  49 ;; arg.
  50
  51 ;; Thanks to everyone for their suggestions for refinements of this
  52 ;; package.  I particularly have to credit Michael Cook, who
  53 ;; implemented an incremental completion style in his 'iswitch'
  54 ;; functions that served as a model for icomplete.  Some other
  55 ;; contributors: Noah Friedman (restructuring as minor mode), Colin
  56 ;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and others.
  57
  58 ;; klm.
  59
  60 ;;; Code:
  61
  62 ;;;_* Provide
  63 (provide 'icomplete)
  64
  65
  66 (defgroup icomplete nil
  67   "Show completions dynamically in minibuffer."
  68   :prefix "icomplete-"
  69   :group 'minibuffer)
  70
  71 (defcustom icomplete-mode nil
  72   "*Toggle incremental minibuffer completion.
  73 As text is typed into the minibuffer, prospective completions are indicated
  74 in the minibuffer.
  75 Setting this variable directly does not take effect;
  76 use either \\[customize] or the function `icomplete-mode'."
  77   :set (lambda (symbol value)
  78          (icomplete-mode (if value 1 -1)))
  79   :initialize 'custom-initialize-default
  80   :type 'boolean
  81   :group 'icomplete
  82   :require 'icomplete)
  83
  84 ;;;_* User Customization variables
  85 (defcustom icomplete-prospects-length 80
  86   "*Length of string displaying the prospects."
  87   :type 'integer
  88   :group 'icomplete)
  89
  90 (defcustom icomplete-compute-delay .3
  91   "*Completions-computation stall, used only with large-number
  92 completions - see `icomplete-delay-completions-threshold'."
  93   :type 'number
  94   :group 'icomplete)
  95
  96 (defcustom icomplete-delay-completions-threshold 400
  97   "*Pending-completions number over which to apply icomplete-compute-delay."
  98   :type 'integer
  99   :group 'icomplete)
 100
 101 (defcustom icomplete-max-delay-chars 3
 102   "*Maximum number of initial chars to apply icomplete compute delay."
 103   :type 'integer
 104   :group 'icomplete)
 105
 106 (defcustom icomplete-show-key-bindings t
 107   "*If non-nil, show key bindings as well as completion for sole matches."
 108   :type 'boolean
 109   :group 'icomplete)
 110
 111 (defcustom icomplete-minibuffer-setup-hook nil
 112   "*Icomplete-specific customization of minibuffer setup.
 113
 114 This hook is run during minibuffer setup iff icomplete will be active.
 115 It is intended for use in customizing icomplete for interoperation
 116 with other features and packages.  For instance:
 117
 118   \(add-hook 'icomplete-minibuffer-setup-hook
 119             \(function
 120              \(lambda ()
 121                \(make-local-variable 'max-mini-window-height)
 122                \(setq max-mini-window-height 3))))
 123
 124 will constrain Emacs to a maximum minibuffer height of 3 lines when
 125 icompletion is occurring."
 126   :type 'hook
 127   :group 'icomplete)
 128
 129
 130 ;;;_* Initialization
 131
 132 ;;;_ + Internal Variables
 133 ;;;_  = icomplete-eoinput 1
 134 (defvar icomplete-eoinput 1
 135   "Point where minibuffer input ends and completion info begins.")
 136 (make-variable-buffer-local 'icomplete-eoinput)
 137 ;;;_  = icomplete-pre-command-hook
 138 (defvar icomplete-pre-command-hook nil
 139   "Incremental-minibuffer-completion pre-command-hook.
 140
 141 Is run in minibuffer before user input when `icomplete-mode' is non-nil.
 142 Use `icomplete-mode' function to set it up properly for incremental
 143 minibuffer completion.")
 144 (add-hook 'icomplete-pre-command-hook 'icomplete-tidy)
 145 ;;;_  = icomplete-post-command-hook
 146 (defvar icomplete-post-command-hook nil
 147   "Incremental-minibuffer-completion post-command-hook.
 148
 149 Is run in minibuffer after user input when `icomplete-mode' is non-nil.
 150 Use `icomplete-mode' function to set it up properly for incremental
 151 minibuffer completion.")
 152 (add-hook 'icomplete-post-command-hook 'icomplete-exhibit)
 153
 154 (defun icomplete-get-keys (func-name)
 155   "Return strings naming keys bound to `func-name', or nil if none.
 156 Examines the prior, not current, buffer, presuming that current buffer
 157 is minibuffer."
 158   (if (commandp func-name)
 159     (save-excursion
 160       (let* ((sym (intern func-name))
 161              (buf (other-buffer))
 162              (map (save-excursion (set-buffer buf) (current-local-map)))
 163              (keys (where-is-internal sym map)))
 164         (if keys
 165             (concat "<"
 166                     (mapconcat 'key-description
 167                                (sort keys
 168                                      #'(lambda (x y)
 169                                          (< (length x) (length y))))
 170                                ", ")
 171                     ">"))))))
 172
 173 ;;;_ > icomplete-mode (&optional prefix)
 174 ;;;###autoload
 175 (defun icomplete-mode (&optional prefix)
 176   "Activate incremental minibuffer completion for this Emacs session.
 177 Deactivates with negative universal argument."
 178   (interactive "p")
 179   (or prefix (setq prefix 0))
 180   (cond ((>= prefix 0)
 181          (setq icomplete-mode t)
 182          ;; The following is not really necessary after first time -
 183          ;; no great loss.
 184          (add-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup))
 185         (t (setq icomplete-mode nil))))
 186
 187 ;;;_ > icomplete-simple-completing-p ()
 188 (defun icomplete-simple-completing-p ()
 189   "Non-nil if current window is minibuffer that's doing simple completion.
 190
 191 Conditions are:
 192    the selected window is a minibuffer,
 193    and not in the middle of macro execution,
 194    and minibuffer-completion-table is not a symbol (which would
 195        indicate some non-standard, non-simple completion mechanism,
 196        like file-name and other custom-func completions)."
 197
 198   (and (window-minibuffer-p (selected-window))
 199        (not executing-kbd-macro)
 200        (not (symbolp minibuffer-completion-table))))
 201
 202 ;;;_ > icomplete-minibuffer-setup ()
 203 ;;;###autoload
 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   (cond ((and icomplete-mode (icomplete-simple-completing-p))
 208          (make-local-hook 'pre-command-hook)
 209          (add-hook 'pre-command-hook
 210                    (function (lambda ()
 211                                (run-hooks 'icomplete-pre-command-hook)))
 212                    nil t)
 213          (make-local-hook 'post-command-hook)
 214          (add-hook 'post-command-hook
 215                    (function (lambda ()
 216                                (run-hooks 'icomplete-post-command-hook)))
 217                    nil t)
 218          (run-hooks 'icomplete-minibuffer-setup-hook))))
 219 ;\f
 220
 221
 222 ;;;_* Completion
 223
 224 ;;;_ > icomplete-tidy ()
 225 (defun icomplete-tidy ()
 226   "Remove completions display \(if any) prior to new user input.
 227 Should be run in on the minibuffer `pre-command-hook'.  See `icomplete-mode'
 228 and `minibuffer-setup-hook'."
 229   (if (icomplete-simple-completing-p)
 230       (if (and (boundp 'icomplete-eoinput)
 231                icomplete-eoinput)
 232
 233           (if (> icomplete-eoinput (point-max))
 234               ;; Oops, got rug pulled out from under us - reinit:
 235               (setq icomplete-eoinput (point-max))
 236             (let ((buffer-undo-list buffer-undo-list )) ; prevent entry
 237               (delete-region icomplete-eoinput (point-max))))
 238
 239         ;; Reestablish the local variable 'cause minibuffer-setup is weird:
 240         (make-local-variable 'icomplete-eoinput)
 241         (setq icomplete-eoinput 1))))
 242
 243 ;;;_ > icomplete-exhibit ()
 244 (defun icomplete-exhibit ()
 245   "Insert icomplete completions display.
 246 Should be run via minibuffer `post-command-hook'.  See `icomplete-mode'
 247 and `minibuffer-setup-hook'."
 248   (if (icomplete-simple-completing-p)
 249       (let ((contents (buffer-substring (minibuffer-prompt-end)(point-max)))
 250             (buffer-undo-list t))
 251         (save-excursion
 252           (goto-char (point-max))
 253                                         ; Register the end of input, so we
 254                                         ; know where the extra stuff
 255                                         ; (match-status info) begins:
 256           (if (not (boundp 'icomplete-eoinput))
 257               ;; In case it got wiped out by major mode business:
 258               (make-local-variable 'icomplete-eoinput))
 259           (setq icomplete-eoinput (point))
 260                                         ; Insert the match-status information:
 261           (if (and (> (point-max) 1)
 262                    (or
 263                     ;; Don't bother with delay after certain number of chars:
 264                     (> (point-max) icomplete-max-delay-chars)
 265                     ;; Don't delay if alternatives number is small enough:
 266                     (if minibuffer-completion-table
 267                         (cond ((numberp minibuffer-completion-table)
 268                                (< minibuffer-completion-table
 269                                   icomplete-delay-completions-threshold))
 270                               ((sequencep minibuffer-completion-table)
 271                                (< (length minibuffer-completion-table)
 272                                   icomplete-delay-completions-threshold))
 273                               ))
 274                     ;; Delay - give some grace time for next keystroke, before
 275                     ;; embarking on computing completions:
 276                     (sit-for icomplete-compute-delay)))
 277               (insert-string
 278                (icomplete-completions contents
 279                                       minibuffer-completion-table
 280                                       minibuffer-completion-predicate
 281                                       (not
 282                                        minibuffer-completion-confirm))))))))
 283
 284 ;;;_ > icomplete-completions (name candidates predicate require-match)
 285 (defun icomplete-completions (name candidates predicate require-match)
 286   "Identify prospective candidates for minibuffer completion.
 287
 288 The display is updated with each minibuffer keystroke during
 289 minibuffer completion.
 290
 291 Prospective completion suffixes (if any) are displayed, bracketed by
 292 one of \(), \[], or \{} pairs.  The choice of brackets is as follows:
 293
 294   \(...) - a single prospect is identified and matching is enforced,
 295   \[...] - a single prospect is identified but matching is optional, or
 296   \{...} - multiple prospects, separated by commas, are indicated, and
 297           further input is required to distinguish a single one.
 298
 299 The displays for unambiguous matches have ` [Matched]' appended
 300 \(whether complete or not), or ` \[No matches]', if no eligible
 301 matches exist.  \(Keybindings for uniquely matched commands
 302 are exhibited within the square braces.)"
 303
 304   ;; 'all-completions' doesn't like empty
 305   ;; minibuffer-completion-table's (ie: (nil))
 306   (if (and (listp candidates) (null (car candidates)))
 307       (setq candidates nil))
 308
 309   (let ((comps (all-completions name candidates predicate))
 310                                         ; "-determined" - only one candidate
 311         (open-bracket-determined (if require-match "(" "["))
 312         (close-bracket-determined (if require-match ")" "]")))
 313     ;; `concat'/`mapconcat' is the slow part.  With the introduction of
 314     ;; `icomplete-prospects-length', there is no need for `catch'/`throw'.
 315     (if (null comps) (format " %sNo matches%s"
 316                              open-bracket-determined
 317                              close-bracket-determined)
 318       (let* ((most-try (try-completion name (mapcar (function list) comps)))
 319              (most (if (stringp most-try) most-try (car comps)))
 320              (most-len (length most))
 321              (determ (and (> most-len (length name))
 322                           (concat open-bracket-determined
 323                                   (substring most (length name))
 324                                   close-bracket-determined)))
 325              (open-bracket-prospects "{")
 326              (close-bracket-prospects "}")
 327                                         ;"-prospects" - more than one candidate
 328              (prospects-len 0)
 329              prospects most-is-exact comp)
 330         (if (eq most-try t)
 331             (setq prospects nil)
 332           (while (and comps (< prospects-len icomplete-prospects-length))
 333             (setq comp (substring (car comps) most-len)
 334                   comps (cdr comps))
 335             (cond ((string-equal comp "") (setq most-is-exact t))
 336                   ((member comp prospects))
 337                   (t (setq prospects (cons comp prospects)
 338                            prospects-len (+ (length comp) 1 prospects-len))))))
 339         (if prospects
 340             (concat determ
 341                     open-bracket-prospects
 342                     (and most-is-exact ",")
 343                     (mapconcat 'identity
 344                                (sort prospects (function string-lessp))
 345                                ",")
 346                     (and comps ",...")
 347                     close-bracket-prospects)
 348           (concat determ
 349                   " [Matched"
 350                   (let ((keys (and icomplete-show-key-bindings
 351                                    (commandp (intern-soft most))
 352                                    (icomplete-get-keys most))))
 353                     (if keys
 354                         (concat "; " keys)
 355                       ""))
 356                   "]"))))))
 357
 358 (if icomplete-mode
 359     (icomplete-mode 1))
 360
 361 ;;;_* Local emacs vars.
 362 ;;;Local variables:
 363 ;;;outline-layout: (-2 :)
 364 ;;;End:
 365
 366 ;;; icomplete.el ends here