Commit | Line | Data |
---|---|---|
fa157191 | 1 | ;;; icomplete.el --- minibuffer completion incremental feedback |
239c87a1 | 2 | |
73b0cd50 | 3 | ;; Copyright (C) 1992-1994, 1997, 1999, 2001-2011 Free Software Foundation, Inc. |
d462ff97 | 4 | |
1934dbf4 GM |
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. | |
be010748 | 9 | ;; Keywords: help, abbrev |
d462ff97 | 10 | |
239c87a1 | 11 | ;; This file is part of GNU Emacs. |
d462ff97 | 12 | |
eb3fa2cf | 13 | ;; GNU Emacs is free software: you can redistribute it and/or modify |
239c87a1 | 14 | ;; it under the terms of the GNU General Public License as published by |
eb3fa2cf GM |
15 | ;; the Free Software Foundation, either version 3 of the License, or |
16 | ;; (at your option) any later version. | |
d462ff97 | 17 | |
239c87a1 RS |
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. | |
c89164c5 | 22 | |
239c87a1 | 23 | ;; You should have received a copy of the GNU General Public License |
eb3fa2cf | 24 | ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |
d462ff97 | 25 | |
239c87a1 | 26 | ;;; Commentary: |
d462ff97 | 27 | |
b578f267 EN |
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 | ||
5e537651 | 33 | ;; See `icomplete-completions' docstring for a description of the |
b578f267 EN |
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 | ||
1934dbf4 GM |
40 | ;; To activate icomplete mode, load the package and use the |
41 | ;; `icomplete-mode' function. You can subsequently deactivate it by | |
42 | ;; invoking the function icomplete-mode with a negative prefix-arg | |
43 | ;; (C-U -1 ESC-x icomplete-mode). Also, you can prevent activation of | |
44 | ;; the mode during package load by first setting the variable | |
45 | ;; `icomplete-mode' to nil. Icompletion can be enabled any time after | |
46 | ;; the package is loaded by invoking icomplete-mode without a prefix | |
47 | ;; arg. | |
92f7d003 | 48 | |
b578f267 EN |
49 | ;; Thanks to everyone for their suggestions for refinements of this |
50 | ;; package. I particularly have to credit Michael Cook, who | |
51 | ;; implemented an incremental completion style in his 'iswitch' | |
52 | ;; functions that served as a model for icomplete. Some other | |
5e537651 | 53 | ;; contributors: Noah Friedman (restructuring as minor mode), Colin |
1be5a284 | 54 | ;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and others. |
b578f267 EN |
55 | |
56 | ;; klm. | |
c89164c5 | 57 | |
239c87a1 RS |
58 | ;;; Code: |
59 | ||
60 | ;;;_* Provide | |
d462ff97 RS |
61 | (provide 'icomplete) |
62 | ||
5e537651 SE |
63 | |
64 | (defgroup icomplete nil | |
65 | "Show completions dynamically in minibuffer." | |
66 | :prefix "icomplete-" | |
67 | :group 'minibuffer) | |
68 | ||
c2d0b538 SM |
69 | (defvar icomplete-prospects-length 80) |
70 | (make-obsolete-variable | |
71 | 'icomplete-prospects-length 'icomplete-prospects-height "23.1") | |
72 | ||
1934dbf4 | 73 | ;;;_* User Customization variables |
c2d0b538 SM |
74 | (defcustom icomplete-prospects-height |
75 | ;; 20 is an estimated common size for the prompt + minibuffer content, to | |
76 | ;; try to guess the number of lines used up by icomplete-prospects-length. | |
77 | (+ 1 (/ (+ icomplete-prospects-length 20) (window-width))) | |
78 | "Maximum number of lines to use in the minibuffer." | |
dfb4dab1 | 79 | :type 'integer |
af09cfd7 JB |
80 | :group 'icomplete |
81 | :version "23.1") | |
1934dbf4 | 82 | |
5e537651 | 83 | (defcustom icomplete-compute-delay .3 |
077aec27 JB |
84 | "Completions-computation stall, used only with large-number completions. |
85 | See `icomplete-delay-completions-threshold'." | |
5e537651 SE |
86 | :type 'number |
87 | :group 'icomplete) | |
88 | ||
89 | (defcustom icomplete-delay-completions-threshold 400 | |
077aec27 | 90 | "Pending-completions number over which to apply `icomplete-compute-delay'." |
5e537651 SE |
91 | :type 'integer |
92 | :group 'icomplete) | |
93 | ||
94 | (defcustom icomplete-max-delay-chars 3 | |
077aec27 | 95 | "Maximum number of initial chars to apply icomplete compute delay." |
5e537651 SE |
96 | :type 'integer |
97 | :group 'icomplete) | |
98 | ||
99 | (defcustom icomplete-show-key-bindings t | |
077aec27 | 100 | "If non-nil, show key bindings as well as completion for sole matches." |
5e537651 SE |
101 | :type 'boolean |
102 | :group 'icomplete) | |
103 | ||
104 | (defcustom icomplete-minibuffer-setup-hook nil | |
077aec27 | 105 | "Icomplete-specific customization of minibuffer setup. |
239c87a1 | 106 | |
4837b516 | 107 | This hook is run during minibuffer setup if icomplete is active. |
239c87a1 | 108 | It is intended for use in customizing icomplete for interoperation |
9c8acefd | 109 | with other features and packages. For instance: |
239c87a1 | 110 | |
92f7d003 | 111 | \(add-hook 'icomplete-minibuffer-setup-hook |
239c87a1 RS |
112 | \(function |
113 | \(lambda () | |
9c8acefd EZ |
114 | \(make-local-variable 'max-mini-window-height) |
115 | \(setq max-mini-window-height 3)))) | |
239c87a1 | 116 | |
9c8acefd | 117 | will constrain Emacs to a maximum minibuffer height of 3 lines when |
5e537651 SE |
118 | icompletion is occurring." |
119 | :type 'hook | |
120 | :group 'icomplete) | |
121 | ||
122 | ||
123 | ;;;_* Initialization | |
d462ff97 | 124 | |
c89164c5 | 125 | ;;;_ + Internal Variables |
47fda8fc | 126 | ;;;_ = icomplete-eoinput nil |
31d4b748 SM |
127 | (defvar icomplete-overlay (make-overlay (point-min) (point-min) nil t t) |
128 | "Overlay used to display the list of completions.") | |
129 | ||
239c87a1 RS |
130 | ;;;_ = icomplete-pre-command-hook |
131 | (defvar icomplete-pre-command-hook nil | |
132 | "Incremental-minibuffer-completion pre-command-hook. | |
133 | ||
134 | Is run in minibuffer before user input when `icomplete-mode' is non-nil. | |
135 | Use `icomplete-mode' function to set it up properly for incremental | |
136 | minibuffer completion.") | |
137 | (add-hook 'icomplete-pre-command-hook 'icomplete-tidy) | |
138 | ;;;_ = icomplete-post-command-hook | |
139 | (defvar icomplete-post-command-hook nil | |
140 | "Incremental-minibuffer-completion post-command-hook. | |
141 | ||
142 | Is run in minibuffer after user input when `icomplete-mode' is non-nil. | |
143 | Use `icomplete-mode' function to set it up properly for incremental | |
144 | minibuffer completion.") | |
145 | (add-hook 'icomplete-post-command-hook 'icomplete-exhibit) | |
146 | ||
92f7d003 | 147 | (defun icomplete-get-keys (func-name) |
8793dabb | 148 | "Return strings naming keys bound to FUNC-NAME, or nil if none. |
1be5a284 RS |
149 | Examines the prior, not current, buffer, presuming that current buffer |
150 | is minibuffer." | |
8793dabb | 151 | (when (commandp func-name) |
92f7d003 KH |
152 | (save-excursion |
153 | (let* ((sym (intern func-name)) | |
78421c58 | 154 | (buf (other-buffer nil t)) |
4afd234b | 155 | (keys (with-current-buffer buf (where-is-internal sym)))) |
8793dabb JB |
156 | (when keys |
157 | (concat "<" | |
158 | (mapconcat 'key-description | |
159 | (sort keys | |
160 | #'(lambda (x y) | |
161 | (< (length x) (length y)))) | |
162 | ", ") | |
163 | ">")))))) | |
397e713b CY |
164 | ;;;_ = icomplete-with-completion-tables |
165 | (defvar icomplete-with-completion-tables '(internal-complete-buffer) | |
166 | "Specialized completion tables with which icomplete should operate. | |
167 | ||
168 | Icomplete does not operate with any specialized completion tables | |
169 | except those on this list.") | |
92f7d003 | 170 | |
239c87a1 | 171 | ;;;_ > icomplete-mode (&optional prefix) |
c89164c5 | 172 | ;;;###autoload |
47fda8fc | 173 | (define-minor-mode icomplete-mode |
4b404c58 | 174 | "Toggle incremental minibuffer completion for this Emacs session. |
4837b516 GM |
175 | With a numeric argument, turn Icomplete mode on if ARG is positive, |
176 | otherwise turn it off." | |
47fda8fc SM |
177 | :global t :group 'icomplete |
178 | (if icomplete-mode | |
4b404c58 GM |
179 | ;; The following is not really necessary after first time - |
180 | ;; no great loss. | |
47fda8fc SM |
181 | (add-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup) |
182 | (remove-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup))) | |
239c87a1 RS |
183 | |
184 | ;;;_ > icomplete-simple-completing-p () | |
185 | (defun icomplete-simple-completing-p () | |
239c87a1 RS |
186 | "Non-nil if current window is minibuffer that's doing simple completion. |
187 | ||
188 | Conditions are: | |
189 | the selected window is a minibuffer, | |
190 | and not in the middle of macro execution, | |
47fda8fc | 191 | and `minibuffer-completion-table' is not a symbol (which would |
81276211 | 192 | indicate some non-standard, non-simple completion mechanism, |
239c87a1 RS |
193 | like file-name and other custom-func completions)." |
194 | ||
195 | (and (window-minibuffer-p (selected-window)) | |
efcf38c7 | 196 | (not executing-kbd-macro) |
c22e3cd4 | 197 | minibuffer-completion-table |
397e713b | 198 | (or (not (functionp minibuffer-completion-table)) |
476d2aef | 199 | (eq icomplete-with-completion-tables t) |
397e713b | 200 | (member minibuffer-completion-table |
3f56acf9 | 201 | icomplete-with-completion-tables)))) |
d183f322 | 202 | |
239c87a1 | 203 | ;;;_ > icomplete-minibuffer-setup () |
239c87a1 | 204 | (defun icomplete-minibuffer-setup () |
239c87a1 | 205 | "Run in minibuffer on activation to establish incremental completion. |
d183f322 | 206 | Usually run by inclusion in `minibuffer-setup-hook'." |
47fda8fc SM |
207 | (when (and icomplete-mode (icomplete-simple-completing-p)) |
208 | (add-hook 'pre-command-hook | |
209 | (lambda () (run-hooks 'icomplete-pre-command-hook)) | |
210 | nil t) | |
211 | (add-hook 'post-command-hook | |
212 | (lambda () (run-hooks 'icomplete-post-command-hook)) | |
213 | nil t) | |
214 | (run-hooks 'icomplete-minibuffer-setup-hook))) | |
1934dbf4 GM |
215 | ;\f |
216 | ||
217 | ||
239c87a1 RS |
218 | ;;;_* Completion |
219 | ||
220 | ;;;_ > icomplete-tidy () | |
221 | (defun icomplete-tidy () | |
222 | "Remove completions display \(if any) prior to new user input. | |
d183f322 | 223 | Should be run in on the minibuffer `pre-command-hook'. See `icomplete-mode' |
239c87a1 | 224 | and `minibuffer-setup-hook'." |
31d4b748 | 225 | (delete-overlay icomplete-overlay)) |
d183f322 | 226 | |
239c87a1 | 227 | ;;;_ > icomplete-exhibit () |
d462ff97 | 228 | (defun icomplete-exhibit () |
239c87a1 | 229 | "Insert icomplete completions display. |
d183f322 | 230 | Should be run via minibuffer `post-command-hook'. See `icomplete-mode' |
239c87a1 | 231 | and `minibuffer-setup-hook'." |
fe689fb6 | 232 | (when (and icomplete-mode (icomplete-simple-completing-p)) |
47fda8fc SM |
233 | (save-excursion |
234 | (goto-char (point-max)) | |
d462ff97 | 235 | ; Insert the match-status information: |
47fda8fc SM |
236 | (if (and (> (point-max) (minibuffer-prompt-end)) |
237 | buffer-undo-list ; Wait for some user input. | |
238 | (or | |
239 | ;; Don't bother with delay after certain number of chars: | |
240 | (> (- (point) (field-beginning)) icomplete-max-delay-chars) | |
241 | ;; Don't delay if alternatives number is small enough: | |
242 | (and (sequencep minibuffer-completion-table) | |
243 | (< (length minibuffer-completion-table) | |
244 | icomplete-delay-completions-threshold)) | |
245 | ;; Delay - give some grace time for next keystroke, before | |
246 | ;; embarking on computing completions: | |
247 | (sit-for icomplete-compute-delay))) | |
248 | (let ((text (while-no-input | |
9a84ddd8 RS |
249 | (icomplete-completions |
250 | (field-string) | |
251 | minibuffer-completion-table | |
252 | minibuffer-completion-predicate | |
31d4b748 | 253 | (not minibuffer-completion-confirm)))) |
7a78ffec EZ |
254 | (buffer-undo-list t) |
255 | deactivate-mark) | |
9a84ddd8 | 256 | ;; Do nothing if while-no-input was aborted. |
31d4b748 SM |
257 | (when (stringp text) |
258 | (move-overlay icomplete-overlay (point) (point) (current-buffer)) | |
259 | ;; The current C cursor code doesn't know to use the overlay's | |
260 | ;; marker's stickiness to figure out whether to place the cursor | |
261 | ;; before or after the string, so let's spoon-feed it the pos. | |
262 | (put-text-property 0 1 'cursor t text) | |
263 | (overlay-put icomplete-overlay 'after-string text))))))) | |
d183f322 | 264 | |
239c87a1 RS |
265 | ;;;_ > icomplete-completions (name candidates predicate require-match) |
266 | (defun icomplete-completions (name candidates predicate require-match) | |
d462ff97 RS |
267 | "Identify prospective candidates for minibuffer completion. |
268 | ||
c89164c5 | 269 | The display is updated with each minibuffer keystroke during |
d462ff97 RS |
270 | minibuffer completion. |
271 | ||
272 | Prospective completion suffixes (if any) are displayed, bracketed by | |
273 | one of \(), \[], or \{} pairs. The choice of brackets is as follows: | |
274 | ||
275 | \(...) - a single prospect is identified and matching is enforced, | |
276 | \[...] - a single prospect is identified but matching is optional, or | |
277 | \{...} - multiple prospects, separated by commas, are indicated, and | |
81276211 | 278 | further input is required to distinguish a single one. |
d462ff97 | 279 | |
81276211 | 280 | The displays for unambiguous matches have ` [Matched]' appended |
d183f322 | 281 | \(whether complete or not), or ` \[No matches]', if no eligible |
1be5a284 | 282 | matches exist. \(Keybindings for uniquely matched commands |
92f7d003 KH |
283 | are exhibited within the square braces.)" |
284 | ||
acd1f317 MA |
285 | (let* ((non-essential t) |
286 | (comps (completion-all-sorted-completions)) | |
31d4b748 SM |
287 | (last (if (consp comps) (last comps))) |
288 | (base-size (cdr last)) | |
476d2aef SM |
289 | (open-bracket (if require-match "(" "[")) |
290 | (close-bracket (if require-match ")" "]"))) | |
c2d0b538 | 291 | ;; `concat'/`mapconcat' is the slow part. |
31d4b748 | 292 | (if (not (consp comps)) |
476d2aef | 293 | (format " %sNo matches%s" open-bracket close-bracket) |
31d4b748 | 294 | (if last (setcdr last nil)) |
be91065f SM |
295 | (let* ((most-try |
296 | (if (and base-size (> base-size 0)) | |
297 | (completion-try-completion | |
298 | name candidates predicate (length name)) | |
299 | ;; If the `comps' are 0-based, the result should be | |
300 | ;; the same with `comps'. | |
301 | (completion-try-completion | |
302 | name comps nil (length name)))) | |
31d4b748 SM |
303 | (most (if (consp most-try) (car most-try) |
304 | (if most-try (car comps) ""))) | |
476d2aef SM |
305 | ;; Compare name and most, so we can determine if name is |
306 | ;; a prefix of most, or something else. | |
307 | (compare (compare-strings name nil nil | |
308 | most nil nil completion-ignore-case)) | |
309 | (determ (unless (or (eq t compare) (eq t most-try) | |
310 | (= (setq compare (1- (abs compare))) | |
311 | (length most))) | |
312 | (concat open-bracket | |
313 | (cond | |
314 | ((= compare (length name)) | |
315 | ;; Typical case: name is a prefix. | |
316 | (substring most compare)) | |
317 | ((< compare 5) most) | |
318 | (t (concat "..." (substring most compare)))) | |
319 | close-bracket))) | |
47fda8fc | 320 | ;;"-prospects" - more than one candidate |
c2d0b538 SM |
321 | (prospects-len (+ (length determ) 6 ;; take {,...} into account |
322 | (string-width (buffer-string)))) | |
323 | (prospects-max | |
324 | ;; Max total length to use, including the minibuffer content. | |
29f313d7 | 325 | (* (+ icomplete-prospects-height |
c2d0b538 SM |
326 | ;; If the minibuffer content already uses up more than |
327 | ;; one line, increase the allowable space accordingly. | |
328 | (/ prospects-len (window-width))) | |
329 | (window-width))) | |
476d2aef SM |
330 | (prefix-len |
331 | ;; Find the common prefix among `comps'. | |
332 | (if (eq t (compare-strings (car comps) nil (length most) | |
31d4b748 | 333 | most nil nil completion-ignore-case)) |
476d2aef SM |
334 | ;; Common case. |
335 | (length most) | |
336 | ;; Else, use try-completion. | |
337 | (let ((comps-prefix (try-completion "" comps))) | |
338 | (and (stringp comps-prefix) | |
339 | (length comps-prefix))))) | |
340 | ||
7d94fb17 | 341 | prospects most-is-exact comp limit) |
31d4b748 | 342 | (if (eq most-try t) ;; (or (null (cdr comps)) |
1934dbf4 | 343 | (setq prospects nil) |
7d94fb17 | 344 | (while (and comps (not limit)) |
476d2aef SM |
345 | (setq comp |
346 | (if prefix-len (substring (car comps) prefix-len) (car comps)) | |
1934dbf4 GM |
347 | comps (cdr comps)) |
348 | (cond ((string-equal comp "") (setq most-is-exact t)) | |
349 | ((member comp prospects)) | |
c2d0b538 SM |
350 | (t (setq prospects-len |
351 | (+ (string-width comp) 1 prospects-len)) | |
352 | (if (< prospects-len prospects-max) | |
31d4b748 | 353 | (push comp prospects) |
7d94fb17 | 354 | (setq limit t)))))) |
31d4b748 SM |
355 | ;; Restore the base-size info, since completion-all-sorted-completions |
356 | ;; is cached. | |
357 | (if last (setcdr last base-size)) | |
1934dbf4 GM |
358 | (if prospects |
359 | (concat determ | |
47fda8fc | 360 | "{" |
1934dbf4 | 361 | (and most-is-exact ",") |
31d4b748 SM |
362 | (mapconcat 'identity (nreverse prospects) ",") |
363 | (and limit ",...") | |
47fda8fc | 364 | "}") |
1934dbf4 GM |
365 | (concat determ |
366 | " [Matched" | |
367 | (let ((keys (and icomplete-show-key-bindings | |
368 | (commandp (intern-soft most)) | |
369 | (icomplete-get-keys most)))) | |
47fda8fc | 370 | (if keys (concat "; " keys) "")) |
1934dbf4 | 371 | "]")))))) |
d462ff97 | 372 | |
476d2aef SM |
373 | ;;_* Local emacs vars. |
374 | ;;Local variables: | |
375 | ;;allout-layout: (-2 :) | |
376 | ;;End: | |
d462ff97 RS |
377 | |
378 | ;;; icomplete.el ends here |