lisp/icomplete.el

   1 ;;; icomplete.el --- minibuffer completion incremental feedback
   2
   3 ;; Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc.
   4
   5 ;; Author: Ken Manheimer <klm@nist.gov>
   6 ;; Maintainer: Ken Manheimer <klm@nist.gov>
   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
  24 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
  25
  26 ;;; Commentary:
  27
  28 ;;; Loading this package implements a more fine-grained minibuffer
  29 ;;; completion feedback scheme.  Prospective completions are concisely
  30 ;;; indicated within the minibuffer itself, with each successive
  31 ;;; keystroke.
  32
  33 ;;; See 'icomplete-completions' docstring for a description of the
  34 ;;; icomplete display format.
  35
  36 ;;; See the `icomplete-minibuffer-setup-hook' docstring for a means to
  37 ;;; customize icomplete setup for interoperation with other
  38 ;;; minibuffer-oriented packages.
  39
  40 ;;; To activate icomplete mode, simply load the package.  You can
  41 ;;; subsequently deactivate it by invoking the function icomplete-mode
  42 ;;; with a negative prefix-arg (C-U -1 ESC-x icomplete-mode).  Also,
  43 ;;; you can prevent activation of the mode during package load by
  44 ;;; first setting the variable `icomplete-mode' to nil.  Icompletion
  45 ;;; can be enabled any time after the package is loaded by invoking
  46 ;;; icomplete-mode without a prefix arg.
  47
  48 ;;; Thanks to everyone for their suggestions for refinements of this
  49 ;;; package.  I particularly have to credit Michael Cook, who
  50 ;;; implemented an incremental completion style in his 'iswitch'
  51 ;;; functions that served as a model for icomplete.  Some other
  52 ;;; contributors: Noah Freidman (restructuring as minor mode), Colin
  53 ;;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and
  54 ;;; others.
  55
  56 ;;; klm.
  57
  58 ;;; Code:
  59
  60 ;;;_* Provide
  61 (provide 'icomplete)
  62
  63 ;;;_* User Customization variables
  64
  65 ;;;_* Initialization
  66 ;;;_  = icomplete-minibuffer-setup-hook
  67 (defvar icomplete-minibuffer-setup-hook nil
  68   "*Icomplete-specific customization of minibuffer setup.
  69
  70 This hook is run during minibuffer setup iff icomplete will be active.
  71 It is intended for use in customizing icomplete for interoperation
  72 with other packages.  For instance:
  73
  74   \(add-hook 'icomplete-minibuffer-setup-hook
  75             \(function
  76              \(lambda ()
  77                \(make-local-variable 'resize-minibuffer-window-max-height)
  78                \(setq resize-minibuffer-window-max-height 3))))
  79
  80 will constrain rsz-mini to a maximum minibuffer height of 3 lines when
  81 icompletion is occurring.")
  82
  83 ;;;_ + Internal Variables
  84 ;;;_  = icomplete-mode
  85 (defvar icomplete-mode t
  86   "Non-nil enables incremental minibuffer completion, once
  87 `\\[icomplete-mode]' function has set things up.")
  88 ;;;_  = icomplete-eoinput 1
  89 (defvar icomplete-eoinput 1
  90   "Point where minibuffer input ends and completion info begins.")
  91 (make-variable-buffer-local 'icomplete-eoinput)
  92 ;;;_  = icomplete-pre-command-hook
  93 (defvar icomplete-pre-command-hook nil
  94   "Incremental-minibuffer-completion pre-command-hook.
  95
  96 Is run in minibuffer before user input when `icomplete-mode' is non-nil.
  97 Use `icomplete-mode' function to set it up properly for incremental
  98 minibuffer completion.")
  99 (add-hook 'icomplete-pre-command-hook 'icomplete-tidy)
 100 ;;;_  = icomplete-post-command-hook
 101 (defvar icomplete-post-command-hook nil
 102   "Incremental-minibuffer-completion post-command-hook.
 103
 104 Is run in minibuffer after user input when `icomplete-mode' is non-nil.
 105 Use `icomplete-mode' function to set it up properly for incremental
 106 minibuffer completion.")
 107 (add-hook 'icomplete-post-command-hook 'icomplete-exhibit)
 108
 109 ;;;_ > icomplete-mode (&optional prefix)
 110 ;;;###autoload
 111 (defun icomplete-mode (&optional prefix)
 112   "Activate incremental minibuffer completion for this emacs session,
 113 or deactivate with negative prefix arg."
 114   (interactive "p")
 115   (or prefix (setq prefix 0))
 116   (cond ((>= prefix 0)
 117          (setq icomplete-mode t)
 118          ;; The following is not really necessary after first time -
 119          ;; no great loss.
 120          (add-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup))
 121         (t (setq icomplete-mode nil))))
 122
 123 ;;;_ > icomplete-simple-completing-p ()
 124 (defun icomplete-simple-completing-p ()
 125
 126   "Non-nil if current window is minibuffer that's doing simple completion.
 127
 128 Conditions are:
 129    the selected window is a minibuffer,
 130    and not in the middle of macro execution,
 131    and minibuffer-completion-table is not a symbol (which would
 132        indicate some non-standard, non-simple completion mechansm,
 133        like file-name and other custom-func completions)."
 134
 135   (and (window-minibuffer-p (selected-window))
 136        (not executing-macro)
 137        (not (symbolp minibuffer-completion-table))))
 138
 139 ;;;_ > icomplete-minibuffer-setup ()
 140 ;;;###autoload
 141 (defun icomplete-minibuffer-setup ()
 142   "Run in minibuffer on activation to establish incremental completion.
 143 Usually run by inclusion in `minibuffer-setup-hook'."
 144   (cond ((and icomplete-mode (icomplete-simple-completing-p))
 145          (make-local-hook 'pre-command-hook)
 146          (add-hook 'pre-command-hook
 147                    (function (lambda ()
 148                                (run-hooks 'icomplete-pre-command-hook)))
 149                    nil t)
 150          (make-local-hook 'post-command-hook)
 151          (add-hook 'post-command-hook
 152                    (function (lambda ()
 153                                (run-hooks 'icomplete-post-command-hook)))
 154                    nil t)
 155          (run-hooks 'icomplete-minibuffer-setup-hook))))
 156 \f
 157 ;;;_* Completion
 158
 159 ;;;_ > icomplete-tidy ()
 160 (defun icomplete-tidy ()
 161   "Remove completions display \(if any) prior to new user input.
 162 Should be run in on the minibuffer `pre-command-hook'.  See `icomplete-mode'
 163 and `minibuffer-setup-hook'."
 164   (if (icomplete-simple-completing-p)
 165       (if (and (boundp 'icomplete-eoinput)
 166                icomplete-eoinput)
 167
 168           (if (> icomplete-eoinput (point-max))
 169               ;; Oops, got rug pulled out from under us - reinit:
 170               (setq icomplete-eoinput (point-max))
 171             (let ((buffer-undo-list buffer-undo-list )) ; prevent entry
 172               (delete-region icomplete-eoinput (point-max))))
 173
 174         ;; Reestablish the local variable 'cause minibuffer-setup is weird:
 175         (make-local-variable 'icomplete-eoinput)
 176         (setq icomplete-eoinput 1))))
 177
 178 ;;;_ > icomplete-exhibit ()
 179 (defun icomplete-exhibit ()
 180   "Insert icomplete completions display.
 181 Should be run via minibuffer `post-command-hook'.  See `icomplete-mode'
 182 and `minibuffer-setup-hook'."
 183   (if (icomplete-simple-completing-p)
 184       (let ((contents (buffer-substring (point-min)(point-max)))
 185             (buffer-undo-list t))
 186         (save-excursion
 187           (goto-char (point-max))
 188                                         ; Register the end of input, so we
 189                                         ; know where the extra stuff
 190                                         ; (match-status info) begins:
 191           (if (not (boundp 'icomplete-eoinput))
 192               ;; In case it got wiped out by major mode business:
 193               (make-local-variable 'icomplete-eoinput))
 194           (setq icomplete-eoinput (point))
 195                                         ; Insert the match-status information:
 196           (if (> (point-max) 1)
 197               (insert-string
 198                (icomplete-completions contents
 199                                       minibuffer-completion-table
 200                                       minibuffer-completion-predicate
 201                                       (not
 202                                        minibuffer-completion-confirm))))))))
 203
 204 ;;;_ > icomplete-completions (name candidates predicate require-match)
 205 (defun icomplete-completions (name candidates predicate require-match)
 206   "Identify prospective candidates for minibuffer completion.
 207
 208 The display is updated with each minibuffer keystroke during
 209 minibuffer completion.
 210
 211 Prospective completion suffixes (if any) are displayed, bracketed by
 212 one of \(), \[], or \{} pairs.  The choice of brackets is as follows:
 213
 214   \(...) - a single prospect is identified and matching is enforced,
 215   \[...] - a single prospect is identified but matching is optional, or
 216   \{...} - multiple prospects, separated by commas, are indicated, and
 217           further input is required to distingish a single one.
 218
 219 The displays for disambiguous matches have ` [Matched]' appended
 220 \(whether complete or not), or ` \[No matches]', if no eligible
 221 matches exist."
 222
 223   (let ((comps (all-completions name candidates predicate))
 224                                         ; "-determined" - only one candidate
 225         (open-bracket-determined (if require-match "(" "["))
 226         (close-bracket-determined (if require-match ")" "]"))
 227                                         ;"-prospects" - more than one candidate
 228         (open-bracket-prospects "{")
 229         (close-bracket-prospects "}")
 230         )
 231     (cond ((null comps) (format " %sNo matches%s"
 232                                 open-bracket-determined
 233                                 close-bracket-determined))
 234           ((null (cdr comps))           ;one match
 235            (concat (if (and (> (length (car comps))
 236                                (length name)))
 237                        (concat open-bracket-determined
 238                                (substring (car comps) (length name))
 239                                close-bracket-determined)
 240                      "")
 241                    " [Matched]"))
 242           (t                            ;multiple matches
 243            (let* ((most (try-completion name candidates predicate))
 244                   (most-len (length most))
 245                   most-is-exact
 246                   (alternatives
 247                    (apply
 248                     (function concat)
 249                     (cdr (apply
 250                           (function nconc)
 251                           (mapcar '(lambda (com)
 252                                      (if (= (length com) most-len)
 253                                          ;; Most is one exact match,
 254                                          ;; note that and leave out
 255                                          ;; for later indication:
 256                                          (progn
 257                                            (setq most-is-exact t)
 258                                            ())
 259                                        (list ","
 260                                              (substring com
 261                                                         most-len))))
 262                                   comps))))))
 263              (concat (and (> most-len (length name))
 264                           (concat open-bracket-determined
 265                                   (substring most (length name))
 266                                   close-bracket-determined))
 267                      open-bracket-prospects
 268                      (if most-is-exact
 269                          (concat "," alternatives)
 270                        alternatives)
 271                      close-bracket-prospects))))))
 272
 273 ;;;_ + Initialization
 274 ;;; If user hasn't setq-default icomplete-mode to nil, then setup for
 275 ;;; activation:
 276 (if icomplete-mode
 277     (icomplete-mode))
 278
 279
 280 ;;;_* Local emacs vars.
 281 ;;;Local variables:
 282 ;;;outline-layout: (-2 :)
 283 ;;;End:
 284
 285 ;;; icomplete.el ends here
 286