*** empty log message ***
[emacs.git] / lisp / icomplete.el
blob344cd9fe18f300a2c93369f55f84d5293e3eecaa
1 ;;; icomplete.el --- minibuffer completion incremental feedback
3 ;; Copyright (C) 1992, 1993, 1994, 1997, 1999 Free Software Foundation, Inc.
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
11 ;; This file is part of GNU Emacs.
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.
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.
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.
28 ;;; Commentary:
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.
35 ;; See `icomplete-completions' docstring for a description of the
36 ;; icomplete display format.
38 ;; See the `icomplete-minibuffer-setup-hook' docstring for a means to
39 ;; customize icomplete setup for interoperation with other
40 ;; minibuffer-oriented packages.
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.
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.
58 ;; klm.
60 ;;; Code:
62 ;;;_* Provide
63 (provide 'icomplete)
66 (defgroup icomplete nil
67 "Show completions dynamically in minibuffer."
68 :prefix "icomplete-"
69 :group 'minibuffer)
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)
84 ;;;_* User Customization variables
85 (defcustom icomplete-prospects-length 80
86 "*Length of string displaying the prospects."
87 :type 'integer
88 :group 'icomplete)
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)
96 (defcustom icomplete-delay-completions-threshold 400
97 "*Pending-completions number over which to apply icomplete-compute-delay."
98 :type 'integer
99 :group 'icomplete)
101 (defcustom icomplete-max-delay-chars 3
102 "*Maximum number of initial chars to apply icomplete compute delay."
103 :type 'integer
104 :group 'icomplete)
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)
111 (defcustom icomplete-minibuffer-setup-hook nil
112 "*Icomplete-specific customization of minibuffer setup.
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 packages. For instance:
118 \(add-hook 'icomplete-minibuffer-setup-hook
119 \(function
120 \(lambda ()
121 \(make-local-variable 'resize-minibuffer-window-max-height)
122 \(setq resize-minibuffer-window-max-height 3))))
124 will constrain rsz-mini to a maximum minibuffer height of 3 lines when
125 icompletion is occurring."
126 :type 'hook
127 :group 'icomplete)
130 ;;;_* Initialization
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.
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.
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)
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 ">"))))))
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))))
187 ;;;_ > icomplete-simple-completing-p ()
188 (defun icomplete-simple-completing-p ()
189 "Non-nil if current window is minibuffer that's doing simple completion.
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)."
198 (and (window-minibuffer-p (selected-window))
199 (not executing-kbd-macro)
200 (not (symbolp minibuffer-completion-table))))
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))))
222 ;;;_* Completion
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)
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))))
239 ;; Reestablish the local variable 'cause minibuffer-setup is weird:
240 (make-local-variable 'icomplete-eoinput)
241 (setq icomplete-eoinput 1))))
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)
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))
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))))))))
284 ;;;_ > icomplete-completions (name candidates predicate require-match)
285 (defun icomplete-completions (name candidates predicate require-match)
286 "Identify prospective candidates for minibuffer completion.
288 The display is updated with each minibuffer keystroke during
289 minibuffer completion.
291 Prospective completion suffixes (if any) are displayed, bracketed by
292 one of \(), \[], or \{} pairs. The choice of brackets is as follows:
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.
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.)"
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))
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 "]"))))))
358 (if icomplete-mode
359 (icomplete-mode 1))
361 ;;;_* Local emacs vars.
362 ;;;Local variables:
363 ;;;outline-layout: (-2 :)
364 ;;;End:
366 ;;; icomplete.el ends here