lisp/icomplete.el

   1 ;;;_. icomplete.el - minibuffer completion incremental feedback
   2
   3 ;; Copyright (C) 1992, 1993, 1994, 1997 Free Software Foundation, Inc.
   4
   5 ;; Author: Ken Manheimer <klm@python.org>
   6 ;; Maintainer: Ken Manheimer <klm@python.org>
   7 ;; Created: Mar 1993 klm@nist.gov - first release to usenet
   8 ;; Keywords: help, abbrev
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software; you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation; either version 2, or (at your option)
  15 ;; any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  24 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  25 ;; Boston, MA 02111-1307, USA.
  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, simply load the package.  You can
  42 ;; subsequently deactivate it by invoking the function icomplete-mode
  43 ;; with a negative prefix-arg (C-U -1 ESC-x icomplete-mode).  Also,
  44 ;; you can prevent activation of the mode during package load by
  45 ;; first setting the variable `icomplete-mode' to nil.  Icompletion
  46 ;; can be enabled any time after the package is loaded by invoking
  47 ;; icomplete-mode without a prefix arg.
  48
  49 ;; This version of icomplete runs on Emacs 19.18 and later.  (It
  50 ;; depends on the incorporation of minibuffer-setup-hook.)  The elisp
  51 ;; archives, ftp://archive.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive,
  52 ;; probably still has a version that works in GNU Emacs v18.
  53
  54 ;; Thanks to everyone for their suggestions for refinements of this
  55 ;; package.  I particularly have to credit Michael Cook, who
  56 ;; implemented an incremental completion style in his 'iswitch'
  57 ;; functions that served as a model for icomplete.  Some other
  58 ;; contributors: Noah Freidman (restructuring as minor mode), Colin
  59 ;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and
  60 ;; others.
  61
  62 ;; klm.
  63
  64 ;;; Code:
  65
  66 ;;;_* Provide
  67 (provide 'icomplete)
  68
  69 ;;;_* User Customization variables
  70 (defvar icomplete-compute-delay .3
  71   "*Completions-computation stall, used only with large-number
  72 completions - see `icomplete-delay-completions-threshold'.")
  73 (defvar icomplete-delay-completions-threshold 400
  74   "*Pending-completions number over which to apply icomplete-compute-delay.")
  75 (defvar icomplete-max-delay-chars 3
  76   "*Maximum number of initial chars to apply icomplete compute delay.")
  77
  78 ;;;_* Initialization
  79 ;;;_  = icomplete-minibuffer-setup-hook
  80 (defvar icomplete-minibuffer-setup-hook nil
  81   "*Icomplete-specific customization of minibuffer setup.
  82
  83 This hook is run during minibuffer setup iff icomplete will be active.
  84 It is intended for use in customizing icomplete for interoperation
  85 with other packages.  For instance:
  86
  87   \(add-hook 'icomplete-minibuffer-setup-hook
  88             \(function
  89              \(lambda ()
  90                \(make-local-variable 'resize-minibuffer-window-max-height)
  91                \(setq resize-minibuffer-window-max-height 3))))
  92
  93 will constrain rsz-mini to a maximum minibuffer height of 3 lines when
  94 icompletion is occurring.")
  95
  96 ;;;_ + Internal Variables
  97 ;;;_  = icomplete-mode
  98 (defvar icomplete-mode t
  99   "Non-nil enables incremental minibuffer completion, once
 100 `\\[icomplete-mode]' function has set things up.")
 101 ;;;_  = icomplete-eoinput 1
 102 (defvar icomplete-eoinput 1
 103   "Point where minibuffer input ends and completion info begins.")
 104 (make-variable-buffer-local 'icomplete-eoinput)
 105 ;;;_  = icomplete-pre-command-hook
 106 (defvar icomplete-pre-command-hook nil
 107   "Incremental-minibuffer-completion pre-command-hook.
 108
 109 Is run in minibuffer before user input when `icomplete-mode' is non-nil.
 110 Use `icomplete-mode' function to set it up properly for incremental
 111 minibuffer completion.")
 112 (add-hook 'icomplete-pre-command-hook 'icomplete-tidy)
 113 ;;;_  = icomplete-post-command-hook
 114 (defvar icomplete-post-command-hook nil
 115   "Incremental-minibuffer-completion post-command-hook.
 116
 117 Is run in minibuffer after user input when `icomplete-mode' is non-nil.
 118 Use `icomplete-mode' function to set it up properly for incremental
 119 minibuffer completion.")
 120 (add-hook 'icomplete-post-command-hook 'icomplete-exhibit)
 121
 122 (defvar icomplete-show-key-bindings (string-match "XEmacs\\|Lucid"
 123                                                   emacs-version)
 124   "When non-nil show key bindings as well as completion when matching
 125 a command.  Currently working only for XEmacs - see `icomplete-get-keys'.")
 126
 127 (defun icomplete-get-keys (func-name)
 128   "Return the keys `func-name' is bound to as a string, or nil if none.
 129   NOTE that this depends on `owindow' minbuf setting and `current-local-map'
 130   taking arg, both present in XEmacs but not present in mainline GNU Emacs
 131   19.34."
 132   (when (commandp func-name)
 133     (save-excursion
 134       (let* ((sym (intern func-name))
 135              (buf (set-buffer (window-buffer owindow)))
 136              (keys (where-is-internal sym (current-local-map buf))))
 137         (if keys
 138             (concat "<"
 139                     (mapconcat 'key-description
 140                                (sort keys
 141                                      #'(lambda (x y)
 142                                          (< (length x) (length y))))
 143                                ", ")
 144                     ">"))))))
 145
 146 ;;;_ > icomplete-mode (&optional prefix)
 147 ;;;###autoload
 148 (defun icomplete-mode (&optional prefix)
 149   "Activate incremental minibuffer completion for this emacs session,
 150 or deactivate with negative prefix arg."
 151   (interactive "p")
 152   (or prefix (setq prefix 0))
 153   (cond ((>= prefix 0)
 154          (setq icomplete-mode t)
 155          ;; The following is not really necessary after first time -
 156          ;; no great loss.
 157          (add-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup))
 158         (t (setq icomplete-mode nil))))
 159
 160 ;;;_ > icomplete-simple-completing-p ()
 161 (defun icomplete-simple-completing-p ()
 162
 163   "Non-nil if current window is minibuffer that's doing simple completion.
 164
 165 Conditions are:
 166    the selected window is a minibuffer,
 167    and not in the middle of macro execution,
 168    and minibuffer-completion-table is not a symbol (which would
 169        indicate some non-standard, non-simple completion mechanism,
 170        like file-name and other custom-func completions)."
 171
 172   (and (window-minibuffer-p (selected-window))
 173        (not executing-kbd-macro)
 174        (not (symbolp minibuffer-completion-table))))
 175
 176 ;;;_ > icomplete-minibuffer-setup ()
 177 ;;;###autoload
 178 (defun icomplete-minibuffer-setup ()
 179   "Run in minibuffer on activation to establish incremental completion.
 180 Usually run by inclusion in `minibuffer-setup-hook'."
 181   (cond ((and icomplete-mode (icomplete-simple-completing-p))
 182          (make-local-hook 'pre-command-hook)
 183          (add-hook 'pre-command-hook
 184                    (function (lambda ()
 185                                (run-hooks 'icomplete-pre-command-hook)))
 186                    nil t)
 187          (make-local-hook 'post-command-hook)
 188          (add-hook 'post-command-hook
 189                    (function (lambda ()
 190                                (run-hooks 'icomplete-post-command-hook)))
 191                    nil t)
 192          (run-hooks 'icomplete-minibuffer-setup-hook))))
 193 \f
 194 ;;;_* Completion
 195
 196 ;;;_ > icomplete-tidy ()
 197 (defun icomplete-tidy ()
 198   "Remove completions display \(if any) prior to new user input.
 199 Should be run in on the minibuffer `pre-command-hook'.  See `icomplete-mode'
 200 and `minibuffer-setup-hook'."
 201   (if (icomplete-simple-completing-p)
 202       (if (and (boundp 'icomplete-eoinput)
 203                icomplete-eoinput)
 204
 205           (if (> icomplete-eoinput (point-max))
 206               ;; Oops, got rug pulled out from under us - reinit:
 207               (setq icomplete-eoinput (point-max))
 208             (let ((buffer-undo-list buffer-undo-list )) ; prevent entry
 209               (delete-region icomplete-eoinput (point-max))))
 210
 211         ;; Reestablish the local variable 'cause minibuffer-setup is weird:
 212         (make-local-variable 'icomplete-eoinput)
 213         (setq icomplete-eoinput 1))))
 214
 215 ;;;_ > icomplete-exhibit ()
 216 (defun icomplete-exhibit ()
 217   "Insert icomplete completions display.
 218
 219 Should be run via minibuffer `post-command-hook'.  See `icomplete-mode'
 220 and `minibuffer-setup-hook'."
 221   (if (icomplete-simple-completing-p)
 222       (let ((contents (buffer-substring (point-min)(point-max)))
 223             (buffer-undo-list t))
 224         (save-excursion
 225           (goto-char (point-max))
 226                                         ; Register the end of input, so we
 227                                         ; know where the extra stuff
 228                                         ; (match-status info) begins:
 229           (if (not (boundp 'icomplete-eoinput))
 230               ;; In case it got wiped out by major mode business:
 231               (make-local-variable 'icomplete-eoinput))
 232           (setq icomplete-eoinput (point))
 233                                         ; Insert the match-status information:
 234           (if (and (> (point-max) 1)
 235                    (or
 236                     ;; Don't bother with delay after certain number of chars:
 237                     (> (point-max) icomplete-max-delay-chars)
 238                     ;; Don't delay if alternatives number is small enough:
 239                     (if minibuffer-completion-table
 240                         (cond ((numberp minibuffer-completion-table)
 241                                (< minibuffer-completion-table
 242                                   icomplete-delay-completions-threshold))
 243                               ((sequencep minibuffer-completion-table)
 244                                (< (length minibuffer-completion-table)
 245                                   icomplete-delay-completions-threshold))
 246                               ))
 247                     ;; Delay - give some grace time for next keystroke, before
 248                     ;; embarking on computing completions:
 249                     (sit-for icomplete-compute-delay)))
 250               (insert-string
 251                (icomplete-completions contents
 252                                       minibuffer-completion-table
 253                                       minibuffer-completion-predicate
 254                                       (not
 255                                        minibuffer-completion-confirm))))))))
 256
 257 ;;;_ > icomplete-completions (name candidates predicate require-match)
 258 (defun icomplete-completions (name candidates predicate require-match)
 259   "Identify prospective candidates for minibuffer completion.
 260
 261 The display is updated with each minibuffer keystroke during
 262 minibuffer completion.
 263
 264 Prospective completion suffixes (if any) are displayed, bracketed by
 265 one of \(), \[], or \{} pairs.  The choice of brackets is as follows:
 266
 267   \(...) - a single prospect is identified and matching is enforced,
 268   \[...] - a single prospect is identified but matching is optional, or
 269   \{...} - multiple prospects, separated by commas, are indicated, and
 270           further input is required to distinguish a single one.
 271
 272 The displays for unambiguous matches have ` [Matched]' appended
 273 \(whether complete or not), or ` \[No matches]', if no eligible
 274 matches exist.  \(In XEmacs, keybindings for matched commands, if any,
 275 are exhibited within the square braces.)"
 276
 277   ;; 'all-completions' doesn't like empty
 278   ;; minibuffer-completion-table's (ie: (nil))
 279   (if (and (listp candidates) (null (car candidates)))
 280       (setq candidates nil))
 281
 282   (let ((comps (all-completions name candidates predicate))
 283                                         ; "-determined" - only one candidate
 284         (open-bracket-determined (if require-match "(" "["))
 285         (close-bracket-determined (if require-match ")" "]"))
 286                                         ;"-prospects" - more than one candidate
 287         (open-bracket-prospects "{")
 288         (close-bracket-prospects "}")
 289         )
 290     (catch 'input
 291       (cond ((null comps) (format " %sNo matches%s"
 292                                   open-bracket-determined
 293                                   close-bracket-determined))
 294             ((null (cdr comps))         ;one match
 295              (concat (if (and (> (length (car comps))
 296                                  (length name)))
 297                          (concat open-bracket-determined
 298                                  (substring (car comps) (length name))
 299                                  close-bracket-determined)
 300                        "")
 301                      " [Matched"
 302                      (let ((keys (and icomplete-show-key-bindings
 303                                       (commandp (intern-soft (car comps)))
 304                                       (icomplete-get-keys (car comps)))))
 305                        (if keys
 306                            (concat "; " keys)
 307                          ""))
 308                      "]"))
 309             (t                          ;multiple matches
 310              (let* ((most
 311                      (try-completion name candidates
 312                                      (and predicate
 313                                           ;; Wrap predicate in impatience - ie,
 314                                           ;; `throw' up when pending input is
 315                                           ;; noticed.  Adds some overhead to
 316                                           ;; predicate, but should be worth it.
 317                                           (function
 318                                            (lambda (item)
 319                                              (if (input-pending-p)
 320                                                  (throw 'input "")
 321                                                (apply predicate
 322                                                       item nil)))))))
 323                     (most-len (length most))
 324                     most-is-exact
 325                     (alternatives
 326                      (substring
 327                       (apply (function concat)
 328                              (mapcar (function
 329                                       (lambda (com)
 330                                         (if (input-pending-p)
 331                                             (throw 'input ""))
 332                                         (if (= (length com) most-len)
 333                                             ;; Most is one exact match,
 334                                             ;; note that and leave out
 335                                             ;; for later indication:
 336                                             (progn
 337                                               (setq most-is-exact t)
 338                                               ())
 339                                           (concat ","
 340                                                   (substring com
 341                                                              most-len)))))
 342                                      comps))
 343                       1)))
 344                (concat (and (> most-len (length name))
 345                             (concat open-bracket-determined
 346                                     (substring most (length name))
 347                                     close-bracket-determined))
 348                        open-bracket-prospects
 349                        (if most-is-exact
 350                            ;; Add a ',' at the front to indicate "complete but
 351                            ;; not unique":
 352                            (concat "," alternatives)
 353                          alternatives)
 354                        close-bracket-prospects)))))))
 355
 356 ;;;_ + Initialization
 357 ;;; If user hasn't setq-default icomplete-mode to nil, then setup for
 358 ;;; activation:
 359 (if icomplete-mode
 360     (icomplete-mode))
 361
 362
 363 ;;;_* Local emacs vars.
 364 ;;;Local variables:
 365 ;;;outline-layout: (-2 :)
 366 ;;;End:
 367
 368 ;;; icomplete.el ends here