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