lisp/icomplete.el

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