1 ;;; icomplete.el --- minibuffer completion incremental feedback
3 ;; Copyright (C) 1992-1994, 1997, 1999, 2001-2014 Free Software
6 ;; Author: Ken Manheimer <klm@i.am>
7 ;; Maintainer: Ken Manheimer <klm@i.am>
8 ;; Created: Mar 1993 Ken Manheimer, klm@nist.gov - first release to usenet
9 ;; Last update: Ken Manheimer <klm@i.am>, 11/18/1999.
10 ;; Keywords: help, abbrev
12 ;; This file is part of GNU Emacs.
14 ;; GNU Emacs is free software: you can redistribute it and/or modify
15 ;; it under the terms of the GNU General Public License as published by
16 ;; the Free Software Foundation, either version 3 of the License, or
17 ;; (at your option) any later version.
19 ;; GNU Emacs is distributed in the hope that it will be useful,
20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 ;; GNU General Public License for more details.
24 ;; You should have received a copy of the GNU General Public License
25 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
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, load the package and use the
42 ;; `icomplete-mode' function. You can subsequently deactivate it by
43 ;; invoking the function icomplete-mode with a negative prefix-arg
44 ;; (C-U -1 ESC-x icomplete-mode). Also, you can prevent activation of
45 ;; the mode during package load by first setting the variable
46 ;; `icomplete-mode' to nil. Icompletion can be enabled any time after
47 ;; the package is loaded by invoking icomplete-mode without a prefix
50 ;; Thanks to everyone for their suggestions for refinements of this
51 ;; package. I particularly have to credit Michael Cook, who
52 ;; implemented an incremental completion style in his 'iswitch'
53 ;; functions that served as a model for icomplete. Some other
54 ;; contributors: Noah Friedman (restructuring as minor mode), Colin
55 ;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and others.
61 (defgroup icomplete nil
62 "Show completions dynamically in minibuffer."
66 (defvar icomplete-prospects-length
80)
67 (make-obsolete-variable
68 'icomplete-prospects-length
'icomplete-prospects-height
"23.1")
70 (defcustom icomplete-separator
" | "
71 "String used by icomplete to separate alternatives in the minibuffer."
75 (defcustom icomplete-hide-common-prefix t
76 "When non-nil, hide common prefix from completion candidates.
77 When nil, show candidates in full."
81 (defcustom icomplete-show-matches-on-no-input nil
82 "When non-nil, show completions when first prompting for input."
86 (defface icomplete-first-match
'((t :weight bold
))
87 "Face used by icomplete for highlighting first match."
90 ;;;_* User Customization variables
91 (defcustom icomplete-prospects-height
92 ;; 20 is an estimated common size for the prompt + minibuffer content, to
93 ;; try to guess the number of lines used up by icomplete-prospects-length.
94 (+ 1 (/ (+ icomplete-prospects-length
20) (window-width)))
95 "Maximum number of lines to use in the minibuffer."
99 (defcustom icomplete-compute-delay
.3
100 "Completions-computation stall, used only with large-number completions.
101 See `icomplete-delay-completions-threshold'."
104 (defcustom icomplete-delay-completions-threshold
400
105 "Pending-completions number over which to apply `icomplete-compute-delay'."
108 (defcustom icomplete-max-delay-chars
3
109 "Maximum number of initial chars to apply icomplete compute delay."
112 (defvar icomplete-in-buffer nil
113 "If non-nil, also use Icomplete when completing in non-mini buffers.")
115 (defcustom icomplete-minibuffer-setup-hook nil
116 "Icomplete-specific customization of minibuffer setup.
118 This hook is run during minibuffer setup if icomplete is active.
119 It is intended for use in customizing icomplete for interoperation
120 with other features and packages. For instance:
122 \(add-hook 'icomplete-minibuffer-setup-hook
125 \(make-local-variable 'max-mini-window-height)
126 \(setq max-mini-window-height 3))))
128 will constrain Emacs to a maximum minibuffer height of 3 lines when
129 icompletion is occurring."
136 ;;;_ + Internal Variables
137 ;;;_ = icomplete-eoinput nil
138 (defvar icomplete-overlay
(make-overlay (point-min) (point-min) nil t t
)
139 "Overlay used to display the list of completions.")
141 (defun icomplete-pre-command-hook ()
142 (let ((non-essential t
))
145 (defun icomplete-post-command-hook ()
146 (let ((non-essential t
)) ;E.g. don't prompt for password!
147 (icomplete-exhibit)))
149 ;;;_ = icomplete-with-completion-tables
150 (defcustom icomplete-with-completion-tables t
151 "Specialized completion tables with which icomplete should operate.
153 If this variable is a list, Icomplete will not operate with any
154 specialized completion tables except those on this list. If this
155 variable is t, it won't restrict completion tables."
157 :type
'(choice (const :tag
"All" t
)
160 (defvar icomplete-minibuffer-map
161 (let ((map (make-sparse-keymap)))
162 (define-key map
[?\M-
\t] 'minibuffer-force-complete
)
163 (define-key map
[?\C-j
] 'minibuffer-force-complete-and-exit
)
164 (define-key map
[?\C-.
] 'icomplete-forward-completions
)
165 (define-key map
[?\C-
,] 'icomplete-backward-completions
)
168 (defun icomplete-forward-completions ()
169 "Step forward completions by one entry.
170 Second entry becomes the first and can be selected with
171 `minibuffer-force-complete-and-exit'."
173 (let* ((beg (icomplete--field-beg))
174 (end (icomplete--field-end))
175 (comps (completion-all-sorted-completions beg end
))
178 (setcdr last
(cons (car comps
) (cdr last
)))
179 (completion--cache-all-sorted-completions beg end
(cdr comps
)))))
181 (defun icomplete-backward-completions ()
182 "Step backward completions by one entry.
183 Last entry becomes the first and can be selected with
184 `minibuffer-force-complete-and-exit'."
186 (let* ((beg (icomplete--field-beg))
187 (end (icomplete--field-end))
188 (comps (completion-all-sorted-completions beg end
))
189 (last-but-one (last comps
2))
190 (last (cdr last-but-one
)))
191 (when (consp last
) ; At least two elements in comps
192 (setcdr last-but-one
(cdr last
))
193 (push (car last
) comps
)
194 (completion--cache-all-sorted-completions beg end comps
))))
196 ;;;_ > icomplete-mode (&optional prefix)
198 (define-minor-mode icomplete-mode
199 "Toggle incremental minibuffer completion (Icomplete mode).
200 With a prefix argument ARG, enable Icomplete mode if ARG is
201 positive, and disable it otherwise. If called from Lisp, enable
202 the mode if ARG is omitted or nil."
203 :global t
:group
'icomplete
204 (remove-hook 'minibuffer-setup-hook
#'icomplete-minibuffer-setup
)
205 (remove-hook 'completion-in-region-mode-hook
#'icomplete--in-region-setup
)
207 (when icomplete-in-buffer
208 (add-hook 'completion-in-region-mode-hook
#'icomplete--in-region-setup
))
209 (add-hook 'minibuffer-setup-hook
#'icomplete-minibuffer-setup
)))
211 (defun icomplete--completion-table ()
212 (if (window-minibuffer-p) minibuffer-completion-table
213 (or (nth 2 completion-in-region--data
)
214 (message "In %S (w=%S): %S"
215 (current-buffer) (selected-window) (window-minibuffer-p)))))
216 (defun icomplete--completion-predicate ()
217 (if (window-minibuffer-p) minibuffer-completion-predicate
218 (nth 3 completion-in-region--data
)))
219 (defun icomplete--field-string ()
220 (if (window-minibuffer-p) (minibuffer-contents)
221 (buffer-substring-no-properties
222 (nth 0 completion-in-region--data
)
223 (nth 1 completion-in-region--data
))))
224 (defun icomplete--field-beg ()
225 (if (window-minibuffer-p) (minibuffer-prompt-end)
226 (nth 0 completion-in-region--data
)))
227 (defun icomplete--field-end ()
228 (if (window-minibuffer-p) (point-max)
229 (nth 1 completion-in-region--data
)))
231 ;;;_ > icomplete-simple-completing-p ()
232 (defun icomplete-simple-completing-p ()
233 "Non-nil if current window is minibuffer that's doing simple completion.
236 the selected window is a minibuffer,
237 and not in the middle of macro execution,
238 and the completion table is not a function (which would
239 indicate some non-standard, non-simple completion mechanism,
240 like file-name and other custom-func completions)."
242 (unless executing-kbd-macro
243 (let ((table (icomplete--completion-table)))
245 (or (not (functionp table
))
246 (eq icomplete-with-completion-tables t
)
247 (member table icomplete-with-completion-tables
))))))
249 ;;;_ > icomplete-minibuffer-setup ()
250 (defun icomplete-minibuffer-setup ()
251 "Run in minibuffer on activation to establish incremental completion.
252 Usually run by inclusion in `minibuffer-setup-hook'."
253 (when (and icomplete-mode
(icomplete-simple-completing-p))
254 (set (make-local-variable 'completion-show-inline-help
) nil
)
255 (use-local-map (make-composed-keymap icomplete-minibuffer-map
256 (current-local-map)))
257 (add-hook 'pre-command-hook
#'icomplete-pre-command-hook nil t
)
258 (add-hook 'post-command-hook
#'icomplete-post-command-hook nil t
)
259 (run-hooks 'icomplete-minibuffer-setup-hook
)
260 (when icomplete-show-matches-on-no-input
261 (icomplete-exhibit))))
263 (defvar icomplete--in-region-buffer nil
)
265 (defun icomplete--in-region-setup ()
266 (when (or (not completion-in-region-mode
)
267 (and icomplete--in-region-buffer
268 (not (eq icomplete--in-region-buffer
(current-buffer)))))
269 (with-current-buffer (or icomplete--in-region-buffer
(current-buffer))
270 (setq icomplete--in-region-buffer nil
)
271 (delete-overlay icomplete-overlay
)
272 (kill-local-variable 'completion-show-inline-help
)
273 (remove-hook 'pre-command-hook
'icomplete-pre-command-hook t
)
274 (remove-hook 'post-command-hook
'icomplete-post-command-hook t
)
276 (when (and completion-in-region-mode
277 icomplete-mode
(icomplete-simple-completing-p))
278 (setq icomplete--in-region-buffer
(current-buffer))
279 (set (make-local-variable 'completion-show-inline-help
) nil
)
280 (let ((tem (assq 'completion-in-region-mode
281 minor-mode-overriding-map-alist
)))
282 (unless (memq icomplete-minibuffer-map
(cdr tem
))
283 (setcdr tem
(make-composed-keymap icomplete-minibuffer-map
285 (add-hook 'pre-command-hook
'icomplete-pre-command-hook nil t
)
286 (add-hook 'post-command-hook
'icomplete-post-command-hook nil t
)))
292 ;;;_ > icomplete-tidy ()
293 (defun icomplete-tidy ()
294 "Remove completions display \(if any) prior to new user input.
295 Should be run in on the minibuffer `pre-command-hook'. See `icomplete-mode'
296 and `minibuffer-setup-hook'."
297 (delete-overlay icomplete-overlay
))
299 ;;;_ > icomplete-exhibit ()
300 (defun icomplete-exhibit ()
301 "Insert icomplete completions display.
302 Should be run via minibuffer `post-command-hook'. See `icomplete-mode'
303 and `minibuffer-setup-hook'."
304 (when (and icomplete-mode
305 (icomplete-simple-completing-p)) ;Shouldn't be necessary.
307 (goto-char (point-max))
308 ; Insert the match-status information:
309 (if (and (or icomplete-show-matches-on-no-input
310 (> (icomplete--field-end) (icomplete--field-beg)))
312 ;; Don't bother with delay after certain number of chars:
313 (> (- (point) (icomplete--field-beg))
314 icomplete-max-delay-chars
)
315 ;; Don't delay if the completions are known.
316 completion-all-sorted-completions
317 ;; Don't delay if alternatives number is small enough:
318 (and (sequencep (icomplete--completion-table))
319 (< (length (icomplete--completion-table))
320 icomplete-delay-completions-threshold
))
321 ;; Delay - give some grace time for next keystroke, before
322 ;; embarking on computing completions:
323 (sit-for icomplete-compute-delay
)))
324 (let* ((field-string (icomplete--field-string))
325 (text (while-no-input
326 (icomplete-completions
328 (icomplete--completion-table)
329 (icomplete--completion-predicate)
330 (if (window-minibuffer-p)
331 (not minibuffer-completion-confirm
)))))
334 ;; Do nothing if while-no-input was aborted.
336 (move-overlay icomplete-overlay
(point) (point) (current-buffer))
337 ;; The current C cursor code doesn't know to use the overlay's
338 ;; marker's stickiness to figure out whether to place the cursor
339 ;; before or after the string, so let's spoon-feed it the pos.
340 (put-text-property 0 1 'cursor t text
)
341 (overlay-put icomplete-overlay
'after-string text
)))))))
343 ;;;_ > icomplete-completions (name candidates predicate require-match)
344 (defun icomplete-completions (name candidates predicate require-match
)
345 "Identify prospective candidates for minibuffer completion.
347 The display is updated with each minibuffer keystroke during
348 minibuffer completion.
350 Prospective completion suffixes (if any) are displayed, bracketed by
351 one of \(), \[], or \{} pairs. The choice of brackets is as follows:
353 \(...) - a single prospect is identified and matching is enforced,
354 \[...] - a single prospect is identified but matching is optional, or
355 \{...} - multiple prospects, separated by commas, are indicated, and
356 further input is required to distinguish a single one.
358 The displays for unambiguous matches have ` [Matched]' appended
359 \(whether complete or not), or ` \[No matches]', if no eligible
360 matches exist. \(Keybindings for uniquely matched commands
361 are exhibited within the square braces.)"
363 (let* ((minibuffer-completion-table candidates
)
364 (minibuffer-completion-predicate predicate
)
365 (md (completion--field-metadata (icomplete--field-beg)))
366 (comps (completion-all-sorted-completions
367 (icomplete--field-beg) (icomplete--field-end)))
368 (last (if (consp comps
) (last comps
)))
369 (base-size (cdr last
))
370 (open-bracket (if require-match
"(" "["))
371 (close-bracket (if require-match
")" "]")))
372 ;; `concat'/`mapconcat' is the slow part.
373 (if (not (consp comps
))
374 (progn ;;(debug (format "Candidates=%S field=%S" candidates name))
375 (format " %sNo matches%s" open-bracket close-bracket
))
376 (if last
(setcdr last nil
))
378 (if (and base-size
(> base-size
0))
379 (completion-try-completion
380 name candidates predicate
(length name
) md
)
381 ;; If the `comps' are 0-based, the result should be
382 ;; the same with `comps'.
383 (completion-try-completion
384 name comps nil
(length name
) md
)))
385 (most (if (consp most-try
) (car most-try
)
386 (if most-try
(car comps
) "")))
387 ;; Compare name and most, so we can determine if name is
388 ;; a prefix of most, or something else.
389 (compare (compare-strings name nil nil
390 most nil nil completion-ignore-case
))
391 (determ (unless (or (eq t compare
) (eq t most-try
)
392 (= (setq compare
(1- (abs compare
)))
396 ((= compare
(length name
))
397 ;; Typical case: name is a prefix.
398 (substring most compare
))
399 ;; Don't bother truncating if it doesn't gain
400 ;; us at least 2 columns.
402 (t (concat "…" (substring most compare
))))
404 ;;"-prospects" - more than one candidate
405 (prospects-len (+ (string-width
406 (or determ
(concat open-bracket close-bracket
)))
407 (string-width icomplete-separator
)
408 3 ;; take {…} into account
409 (string-width (buffer-string))))
411 ;; Max total length to use, including the minibuffer content.
412 (* (+ icomplete-prospects-height
413 ;; If the minibuffer content already uses up more than
414 ;; one line, increase the allowable space accordingly.
415 (/ prospects-len
(window-width)))
417 ;; Find the common prefix among `comps'.
418 ;; We can't use the optimization below because its assumptions
419 ;; aren't always true, e.g. when completion-cycling (bug#10850):
420 ;; (if (eq t (compare-strings (car comps) nil (length most)
421 ;; most nil nil completion-ignore-case))
424 ;; Else, use try-completion.
425 (prefix (when icomplete-hide-common-prefix
426 (try-completion "" comps
)))
428 (and (stringp prefix
)
429 ;; Only hide the prefix if the corresponding info
430 ;; is already displayed via `most'.
431 (string-prefix-p prefix most t
)
432 (length prefix
))) ;;)
433 prospects comp limit
)
434 (if (or (eq most-try t
) (not (consp (cdr comps
))))
436 (when (member name comps
)
437 ;; NAME is complete but not unique. This scenario poses
438 ;; following UI issues:
440 ;; - When `icomplete-hide-common-prefix' is non-nil, NAME
441 ;; is stripped empty. This would make the entry
444 ;; - Due to sorting of completions, NAME may not be the
445 ;; first of the prospects and could be hidden deep in
446 ;; the displayed string.
448 ;; - Because of `icomplete-prospects-height' , NAME may
449 ;; not even be displayed to the user.
451 ;; To circumvent all the above problems, provide a visual
452 ;; cue to the user via an "empty string" in the try
454 (setq determ
(concat open-bracket
"" close-bracket
)))
455 ;; Compute prospects for display.
456 (while (and comps
(not limit
))
458 (if prefix-len
(substring (car comps
) prefix-len
) (car comps
))
461 (+ (string-width comp
)
462 (string-width icomplete-separator
)
464 (if (< prospects-len prospects-max
)
465 (push comp prospects
)
467 (setq prospects
(nreverse prospects
))
468 ;; Decorate first of the prospects.
470 (let ((first (copy-sequence (pop prospects
))))
471 (put-text-property 0 (length first
)
472 'face
'icomplete-first-match first
)
473 (push first prospects
)))
474 ;; Restore the base-size info, since completion-all-sorted-completions
476 (if last
(setcdr last base-size
))
480 (mapconcat 'identity prospects icomplete-separator
)
481 (and limit
(concat icomplete-separator
"…"))
483 (concat determ
" [Matched]"))))))
488 ;;_* Local emacs vars.
490 ;;allout-layout: (-2 :)
493 ;;; icomplete.el ends here