1 ;;; icomplete.el --- minibuffer completion incremental feedback
3 ;; Copyright (C) 1992, 1993, 1994, 1997 Free Software Foundation, Inc.
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
10 ;; This file is part of GNU Emacs.
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)
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.
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.
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
34 ;; See `icomplete-completions' docstring for a description of the
35 ;; icomplete display format.
37 ;; See the `icomplete-minibuffer-setup-hook' docstring for a means to
38 ;; customize icomplete setup for interoperation with other
39 ;; minibuffer-oriented packages.
41 ;; To activate icomplete mode, simply add the following to .emacs:
43 ;; You can subsequently deactivate it by invoking the function
44 ;; icomplete-mode with a negative prefix-arg (C-U -1 ESC-x
45 ;; icomplete-mode). Also, you can prevent activation of the mode
46 ;; during package load by first setting the variable `icomplete-mode'
47 ;; to nil. Icompletion can be enabled any time after the package is
48 ;; loaded by invoking icomplete-mode without a prefix arg.
50 ;; This version of icomplete runs on Emacs 19.18 and later. (It
51 ;; depends on the incorporation of minibuffer-setup-hook.) The elisp
52 ;; archives, ftp://archive.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive,
53 ;; probably still has a version that works in GNU Emacs v18.
55 ;; Thanks to everyone for their suggestions for refinements of this
56 ;; package. I particularly have to credit Michael Cook, who
57 ;; implemented an incremental completion style in his 'iswitch'
58 ;; functions that served as a model for icomplete. Some other
59 ;; contributors: Noah Friedman (restructuring as minor mode), Colin
60 ;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and others.
70 (defgroup icomplete nil
71 "Show completions dynamically in minibuffer."
75 ;;;_* User Customization variables
76 (defcustom icomplete-mode nil
77 "*Non-nil enables incremental minibuffer completion.
78 As text is typed into the minibuffer, prospective completions are indicated
80 You must modify via \\[customize] for this variable to have an effect."
81 :set
(lambda (symbol value
)
82 (icomplete-mode (if value
1 -
1)))
83 :initialize
'custom-initialize-default
88 (defcustom icomplete-compute-delay
.3
89 "*Completions-computation stall, used only with large-number
90 completions - see `icomplete-delay-completions-threshold'."
94 (defcustom icomplete-delay-completions-threshold
400
95 "*Pending-completions number over which to apply icomplete-compute-delay."
99 (defcustom icomplete-max-delay-chars
3
100 "*Maximum number of initial chars to apply icomplete compute delay."
104 (defcustom icomplete-show-key-bindings t
105 "*If non-nil, show key bindings as well as completion for sole matches."
109 (defcustom icomplete-minibuffer-setup-hook nil
110 "*Icomplete-specific customization of minibuffer setup.
112 This hook is run during minibuffer setup iff icomplete will be active.
113 It is intended for use in customizing icomplete for interoperation
114 with other packages. For instance:
116 \(add-hook 'icomplete-minibuffer-setup-hook
119 \(make-local-variable 'resize-minibuffer-window-max-height)
120 \(setq resize-minibuffer-window-max-height 3))))
122 will constrain rsz-mini to a maximum minibuffer height of 3 lines when
123 icompletion is occurring."
130 ;;;_ + Internal Variables
131 ;;;_ = icomplete-eoinput 1
132 (defvar icomplete-eoinput
1
133 "Point where minibuffer input ends and completion info begins.")
134 (make-variable-buffer-local 'icomplete-eoinput
)
135 ;;;_ = icomplete-pre-command-hook
136 (defvar icomplete-pre-command-hook nil
137 "Incremental-minibuffer-completion pre-command-hook.
139 Is run in minibuffer before user input when `icomplete-mode' is non-nil.
140 Use `icomplete-mode' function to set it up properly for incremental
141 minibuffer completion.")
142 (add-hook 'icomplete-pre-command-hook
'icomplete-tidy
)
143 ;;;_ = icomplete-post-command-hook
144 (defvar icomplete-post-command-hook nil
145 "Incremental-minibuffer-completion post-command-hook.
147 Is run in minibuffer after user input when `icomplete-mode' is non-nil.
148 Use `icomplete-mode' function to set it up properly for incremental
149 minibuffer completion.")
150 (add-hook 'icomplete-post-command-hook
'icomplete-exhibit
)
152 (defun icomplete-get-keys (func-name)
153 "Return strings naming keys bound to `func-name', or nil if none.
154 Examines the prior, not current, buffer, presuming that current buffer
156 (if (commandp func-name
)
158 (let* ((sym (intern func-name
))
160 (map (save-excursion (set-buffer buf
) (current-local-map)))
161 (keys (where-is-internal sym map
)))
164 (mapconcat 'key-description
167 (< (length x
) (length y
))))
171 ;;;_ > icomplete-mode (&optional prefix)
173 (defun icomplete-mode (&optional prefix
)
174 "Activate incremental minibuffer completion for this Emacs session.
175 Deactivates with negative universal argument."
177 (or prefix
(setq prefix
0))
179 (setq icomplete-mode t
)
180 ;; The following is not really necessary after first time -
182 (add-hook 'minibuffer-setup-hook
'icomplete-minibuffer-setup
))
183 (t (setq icomplete-mode nil
))))
185 ;;;_ > icomplete-simple-completing-p ()
186 (defun icomplete-simple-completing-p ()
187 "Non-nil if current window is minibuffer that's doing simple completion.
190 the selected window is a minibuffer,
191 and not in the middle of macro execution,
192 and minibuffer-completion-table is not a symbol (which would
193 indicate some non-standard, non-simple completion mechanism,
194 like file-name and other custom-func completions)."
196 (and (window-minibuffer-p (selected-window))
197 (not executing-kbd-macro
)
198 (not (symbolp minibuffer-completion-table
))))
200 ;;;_ > icomplete-minibuffer-setup ()
202 (defun icomplete-minibuffer-setup ()
203 "Run in minibuffer on activation to establish incremental completion.
204 Usually run by inclusion in `minibuffer-setup-hook'."
205 (cond ((and icomplete-mode
(icomplete-simple-completing-p))
206 (make-local-hook 'pre-command-hook
)
207 (add-hook 'pre-command-hook
209 (run-hooks 'icomplete-pre-command-hook
)))
211 (make-local-hook 'post-command-hook
)
212 (add-hook 'post-command-hook
214 (run-hooks 'icomplete-post-command-hook
)))
216 (run-hooks 'icomplete-minibuffer-setup-hook
))))
220 ;;;_ > icomplete-tidy ()
221 (defun icomplete-tidy ()
222 "Remove completions display \(if any) prior to new user input.
223 Should be run in on the minibuffer `pre-command-hook'. See `icomplete-mode'
224 and `minibuffer-setup-hook'."
225 (if (icomplete-simple-completing-p)
226 (if (and (boundp 'icomplete-eoinput
)
229 (if (> icomplete-eoinput
(point-max))
230 ;; Oops, got rug pulled out from under us - reinit:
231 (setq icomplete-eoinput
(point-max))
232 (let ((buffer-undo-list buffer-undo-list
)) ; prevent entry
233 (delete-region icomplete-eoinput
(point-max))))
235 ;; Reestablish the local variable 'cause minibuffer-setup is weird:
236 (make-local-variable 'icomplete-eoinput
)
237 (setq icomplete-eoinput
1))))
239 ;;;_ > icomplete-exhibit ()
240 (defun icomplete-exhibit ()
241 "Insert icomplete completions display.
242 Should be run via minibuffer `post-command-hook'. See `icomplete-mode'
243 and `minibuffer-setup-hook'."
244 (if (icomplete-simple-completing-p)
245 (let ((contents (buffer-substring (point-min)(point-max)))
246 (buffer-undo-list t
))
248 (goto-char (point-max))
249 ; Register the end of input, so we
250 ; know where the extra stuff
251 ; (match-status info) begins:
252 (if (not (boundp 'icomplete-eoinput
))
253 ;; In case it got wiped out by major mode business:
254 (make-local-variable 'icomplete-eoinput
))
255 (setq icomplete-eoinput
(point))
256 ; Insert the match-status information:
257 (if (and (> (point-max) 1)
259 ;; Don't bother with delay after certain number of chars:
260 (> (point-max) icomplete-max-delay-chars
)
261 ;; Don't delay if alternatives number is small enough:
262 (if minibuffer-completion-table
263 (cond ((numberp minibuffer-completion-table
)
264 (< minibuffer-completion-table
265 icomplete-delay-completions-threshold
))
266 ((sequencep minibuffer-completion-table
)
267 (< (length minibuffer-completion-table
)
268 icomplete-delay-completions-threshold
))
270 ;; Delay - give some grace time for next keystroke, before
271 ;; embarking on computing completions:
272 (sit-for icomplete-compute-delay
)))
274 (icomplete-completions contents
275 minibuffer-completion-table
276 minibuffer-completion-predicate
278 minibuffer-completion-confirm
))))))))
280 ;;;_ > icomplete-completions (name candidates predicate require-match)
281 (defun icomplete-completions (name candidates predicate require-match
)
282 "Identify prospective candidates for minibuffer completion.
284 The display is updated with each minibuffer keystroke during
285 minibuffer completion.
287 Prospective completion suffixes (if any) are displayed, bracketed by
288 one of \(), \[], or \{} pairs. The choice of brackets is as follows:
290 \(...) - a single prospect is identified and matching is enforced,
291 \[...] - a single prospect is identified but matching is optional, or
292 \{...} - multiple prospects, separated by commas, are indicated, and
293 further input is required to distinguish a single one.
295 The displays for unambiguous matches have ` [Matched]' appended
296 \(whether complete or not), or ` \[No matches]', if no eligible
297 matches exist. \(Keybindings for uniquely matched commands
298 are exhibited within the square braces.)"
300 ;; 'all-completions' doesn't like empty
301 ;; minibuffer-completion-table's (ie: (nil))
302 (if (and (listp candidates
) (null (car candidates
)))
303 (setq candidates nil
))
305 (let ((comps (all-completions name candidates predicate
))
306 ; "-determined" - only one candidate
307 (open-bracket-determined (if require-match
"(" "["))
308 (close-bracket-determined (if require-match
")" "]"))
309 ;"-prospects" - more than one candidate
310 (open-bracket-prospects "{")
311 (close-bracket-prospects "}")
314 (cond ((null comps
) (format " %sNo matches%s"
315 open-bracket-determined
316 close-bracket-determined
))
317 ((null (cdr comps
)) ;one match
318 (concat (if (and (> (length (car comps
))
320 (concat open-bracket-determined
321 (substring (car comps
) (length name
))
322 close-bracket-determined
)
325 (let ((keys (and icomplete-show-key-bindings
326 (commandp (intern-soft (car comps
)))
327 (icomplete-get-keys (car comps
)))))
334 (try-completion name candidates
336 ;; Wrap predicate in impatience - ie,
337 ;; `throw' up when pending input is
338 ;; noticed. Adds some overhead to
339 ;; predicate, but should be worth it.
342 (if (input-pending-p)
346 (most-len (length most
))
350 (apply (function concat
)
353 (if (input-pending-p)
355 (if (= (length com
) most-len
)
356 ;; Most is one exact match,
357 ;; note that and leave out
358 ;; for later indication:
360 (setq most-is-exact t
)
367 (concat (and (> most-len
(length name
))
368 (concat open-bracket-determined
369 (substring most
(length name
))
370 close-bracket-determined
))
371 open-bracket-prospects
373 ;; Add a ',' at the front to indicate "complete but
375 (concat "," alternatives
)
377 close-bracket-prospects
)))))))
382 ;;;_* Local emacs vars.
384 ;;;outline-layout: (-2 :)
387 ;;; icomplete.el ends here