Avoid a custom-variable-type error (bug#27363)
[emacs.git] / lisp / icomplete.el
bloba4153e806df9c8bec892c169a6e227c26908b1e8
1 ;;; icomplete.el --- minibuffer completion incremental feedback
3 ;; Copyright (C) 1992-1994, 1997, 1999, 2001-2017 Free Software
4 ;; Foundation, Inc.
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 ;; 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 3 of the License, or
16 ;; (at your option) 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. If not, see <http://www.gnu.org/licenses/>.
26 ;;; Commentary:
28 ;; Enabling 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.
33 ;; See `icomplete-completions' docstring for a description of the
34 ;; icomplete display format.
36 ;; See the `icomplete-minibuffer-setup-hook' docstring for a means to
37 ;; customize icomplete setup for interoperation with other
38 ;; minibuffer-oriented packages.
40 ;; To enable/disable icomplete mode, use the `icomplete-mode' function.
42 ;; Thanks to everyone for their suggestions for refinements of this
43 ;; package. I particularly have to credit Michael Cook, who
44 ;; implemented an incremental completion style in his 'iswitch'
45 ;; functions that served as a model for icomplete. Some other
46 ;; contributors: Noah Friedman (restructuring as minor mode), Colin
47 ;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and others.
49 ;; klm.
51 ;;; Code:
53 (defgroup icomplete nil
54 "Show completions dynamically in minibuffer."
55 :prefix "icomplete-"
56 :link '(info-link "(emacs)Icomplete")
57 :group 'minibuffer)
59 (defcustom icomplete-separator " | "
60 "String used by Icomplete to separate alternatives in the minibuffer."
61 :type 'string
62 :version "24.4")
64 (defcustom icomplete-hide-common-prefix t
65 "When non-nil, hide common prefix from completion candidates.
66 When nil, show candidates in full."
67 :type 'boolean
68 :version "24.4")
70 (defcustom icomplete-show-matches-on-no-input nil
71 "When non-nil, show completions when first prompting for input."
72 :type 'boolean
73 :version "24.4")
75 (defcustom icomplete-with-completion-tables t
76 "Specialized completion tables with which Icomplete should operate.
77 If this is t, Icomplete operates on all tables.
78 Otherwise this should be a list of the completion tables (e.g.,
79 `internal-complete-buffer') on which Icomplete should operate."
80 ;; Prior to 24.4, not a user-option, default '(internal-complete-buffer).
81 :version "24.4"
82 :type '(choice (const :tag "All" t)
83 (repeat function)))
85 (defface icomplete-first-match '((t :weight bold))
86 "Face used by Icomplete for highlighting first match."
87 :version "24.4")
89 ;;;_* User Customization variables
90 (defcustom icomplete-prospects-height 2
91 ;; We used to compute how many lines 100 characters would take in
92 ;; the current window width, but the return value of `window-width'
93 ;; is unreliable on startup (e.g., if we're in daemon mode), so now
94 ;; we simply base the default value on an 80 column window.
95 "Maximum number of lines to use in the minibuffer."
96 :type 'integer
97 :version "26.1")
99 (defcustom icomplete-compute-delay .3
100 "Completions-computation stall, used only with large-number completions.
101 See `icomplete-delay-completions-threshold'."
102 :type 'number)
104 (defcustom icomplete-delay-completions-threshold 400
105 "Pending-completions number over which to apply `icomplete-compute-delay'."
106 :type 'integer)
108 (defcustom icomplete-max-delay-chars 3
109 "Maximum number of initial chars to apply `icomplete-compute-delay'."
110 :type 'integer)
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
123 (lambda () (setq-local max-mini-window-height 3)))
125 will constrain Emacs to a maximum minibuffer height of 3 lines when
126 icompletion is occurring."
127 :type 'hook
128 :group 'icomplete)
131 ;;;_* Initialization
133 ;;;_ + Internal Variables
134 ;;;_ = icomplete-eoinput nil
135 (defvar icomplete-overlay (make-overlay (point-min) (point-min) nil t t)
136 "Overlay used to display the list of completions.")
138 (defun icomplete-pre-command-hook ()
139 (let ((non-essential t))
140 (icomplete-tidy)))
142 (defun icomplete-post-command-hook ()
143 (let ((non-essential t)) ;E.g. don't prompt for password!
144 (icomplete-exhibit)))
146 (defvar icomplete-minibuffer-map
147 (let ((map (make-sparse-keymap)))
148 (define-key map [?\M-\t] 'minibuffer-force-complete)
149 (define-key map [?\C-j] 'icomplete-force-complete-and-exit)
150 (define-key map [?\C-.] 'icomplete-forward-completions)
151 (define-key map [?\C-,] 'icomplete-backward-completions)
152 map)
153 "Keymap used by `icomplete-mode' in the minibuffer.")
155 (defun icomplete-force-complete-and-exit ()
156 "Complete the minibuffer and exit.
157 Use the first of the matches if there are any displayed, and use
158 the default otherwise."
159 (interactive)
160 (if (or icomplete-show-matches-on-no-input
161 (> (icomplete--field-end) (icomplete--field-beg)))
162 (minibuffer-force-complete-and-exit)
163 (minibuffer-complete-and-exit)))
165 (defun icomplete-forward-completions ()
166 "Step forward completions by one entry.
167 Second entry becomes the first and can be selected with
168 `icomplete-force-complete-and-exit'."
169 (interactive)
170 (let* ((beg (icomplete--field-beg))
171 (end (icomplete--field-end))
172 (comps (completion-all-sorted-completions beg end))
173 (last (last comps)))
174 (when comps
175 (setcdr last (cons (car comps) (cdr last)))
176 (completion--cache-all-sorted-completions beg end (cdr comps)))))
178 (defun icomplete-backward-completions ()
179 "Step backward completions by one entry.
180 Last entry becomes the first and can be selected with
181 `icomplete-force-complete-and-exit'."
182 (interactive)
183 (let* ((beg (icomplete--field-beg))
184 (end (icomplete--field-end))
185 (comps (completion-all-sorted-completions beg end))
186 (last-but-one (last comps 2))
187 (last (cdr last-but-one)))
188 (when (consp last) ; At least two elements in comps
189 (setcdr last-but-one (cdr last))
190 (push (car last) comps)
191 (completion--cache-all-sorted-completions beg end comps))))
193 ;;;_ > icomplete-mode (&optional prefix)
194 ;;;###autoload
195 (define-minor-mode icomplete-mode
196 "Toggle incremental minibuffer completion (Icomplete mode).
197 With a prefix argument ARG, enable Icomplete mode if ARG is
198 positive, and disable it otherwise. If called from Lisp, enable
199 the mode if ARG is omitted or nil.
201 When this global minor mode is enabled, typing in the minibuffer
202 continuously displays a list of possible completions that match
203 the string you have typed. See `icomplete-completions' for a
204 description of how prospective completions are displayed.
206 For more information, see Info node `(emacs)Icomplete'.
207 For options you can set, `\\[customize-group] icomplete'.
209 You can use the following key bindings to navigate and select
210 completions:
212 \\{icomplete-minibuffer-map}"
213 :global t :group 'icomplete
214 (remove-hook 'minibuffer-setup-hook #'icomplete-minibuffer-setup)
215 (remove-hook 'completion-in-region-mode-hook #'icomplete--in-region-setup)
216 (when icomplete-mode
217 (when icomplete-in-buffer
218 (add-hook 'completion-in-region-mode-hook #'icomplete--in-region-setup))
219 (add-hook 'minibuffer-setup-hook #'icomplete-minibuffer-setup)))
221 (defun icomplete--completion-table ()
222 (if (window-minibuffer-p) minibuffer-completion-table
223 (or (nth 2 completion-in-region--data)
224 (message "In %S (w=%S): %S"
225 (current-buffer) (selected-window) (window-minibuffer-p)))))
226 (defun icomplete--completion-predicate ()
227 (if (window-minibuffer-p) minibuffer-completion-predicate
228 (nth 3 completion-in-region--data)))
229 (defun icomplete--field-string ()
230 (if (window-minibuffer-p) (minibuffer-contents)
231 (buffer-substring-no-properties
232 (nth 0 completion-in-region--data)
233 (nth 1 completion-in-region--data))))
234 (defun icomplete--field-beg ()
235 (if (window-minibuffer-p) (minibuffer-prompt-end)
236 (nth 0 completion-in-region--data)))
237 (defun icomplete--field-end ()
238 (if (window-minibuffer-p) (point-max)
239 (nth 1 completion-in-region--data)))
241 ;;;_ > icomplete-simple-completing-p ()
242 (defun icomplete-simple-completing-p ()
243 "Non-nil if current window is a minibuffer that's doing simple completion.
245 Conditions are:
246 the selected window is a minibuffer,
247 and not in the middle of macro execution,
248 and the completion table is not a function (which would
249 indicate some non-standard, non-simple completion mechanism,
250 like file-name and other custom-func completions),
251 and `icomplete-with-completion-tables' doesn't restrict completion."
253 (unless executing-kbd-macro
254 (let ((table (icomplete--completion-table)))
255 (and table
256 (or (not (functionp table))
257 (eq icomplete-with-completion-tables t)
258 (member table icomplete-with-completion-tables))))))
260 ;;;_ > icomplete-minibuffer-setup ()
261 (defun icomplete-minibuffer-setup ()
262 "Run in minibuffer on activation to establish incremental completion.
263 Usually run by inclusion in `minibuffer-setup-hook'."
264 (when (and icomplete-mode (icomplete-simple-completing-p))
265 (set (make-local-variable 'completion-show-inline-help) nil)
266 (use-local-map (make-composed-keymap icomplete-minibuffer-map
267 (current-local-map)))
268 (add-hook 'pre-command-hook #'icomplete-pre-command-hook nil t)
269 (add-hook 'post-command-hook #'icomplete-post-command-hook nil t)
270 (run-hooks 'icomplete-minibuffer-setup-hook)
271 (when icomplete-show-matches-on-no-input
272 (icomplete-exhibit))))
274 (defvar icomplete--in-region-buffer nil)
276 (defun icomplete--in-region-setup ()
277 (when (or (not completion-in-region-mode)
278 (and icomplete--in-region-buffer
279 (not (eq icomplete--in-region-buffer (current-buffer)))))
280 (with-current-buffer (or icomplete--in-region-buffer (current-buffer))
281 (setq icomplete--in-region-buffer nil)
282 (delete-overlay icomplete-overlay)
283 (kill-local-variable 'completion-show-inline-help)
284 (remove-hook 'pre-command-hook 'icomplete-pre-command-hook t)
285 (remove-hook 'post-command-hook 'icomplete-post-command-hook t)
286 (message nil)))
287 (when (and completion-in-region-mode
288 icomplete-mode (icomplete-simple-completing-p))
289 (setq icomplete--in-region-buffer (current-buffer))
290 (set (make-local-variable 'completion-show-inline-help) nil)
291 (let ((tem (assq 'completion-in-region-mode
292 minor-mode-overriding-map-alist)))
293 (unless (memq icomplete-minibuffer-map (cdr tem))
294 (setcdr tem (make-composed-keymap icomplete-minibuffer-map
295 (cdr tem)))))
296 (add-hook 'pre-command-hook 'icomplete-pre-command-hook nil t)
297 (add-hook 'post-command-hook 'icomplete-post-command-hook nil t)))
301 ;;;_* Completion
303 ;;;_ > icomplete-tidy ()
304 (defun icomplete-tidy ()
305 "Remove completions display (if any) prior to new user input.
306 Should be run in on the minibuffer `pre-command-hook'.
307 See `icomplete-mode' and `minibuffer-setup-hook'."
308 (delete-overlay icomplete-overlay))
310 ;;;_ > icomplete-exhibit ()
311 (defun icomplete-exhibit ()
312 "Insert Icomplete completions display.
313 Should be run via minibuffer `post-command-hook'.
314 See `icomplete-mode' and `minibuffer-setup-hook'."
315 (when (and icomplete-mode
316 (icomplete-simple-completing-p)) ;Shouldn't be necessary.
317 (save-excursion
318 (goto-char (point-max))
319 ; Insert the match-status information:
320 (if (and (or icomplete-show-matches-on-no-input
321 (> (icomplete--field-end) (icomplete--field-beg)))
323 ;; Don't bother with delay after certain number of chars:
324 (> (- (point) (icomplete--field-beg))
325 icomplete-max-delay-chars)
326 ;; Don't delay if the completions are known.
327 completion-all-sorted-completions
328 ;; Don't delay if alternatives number is small enough:
329 (and (sequencep (icomplete--completion-table))
330 (< (length (icomplete--completion-table))
331 icomplete-delay-completions-threshold))
332 ;; Delay - give some grace time for next keystroke, before
333 ;; embarking on computing completions:
334 (sit-for icomplete-compute-delay)))
335 (let* ((field-string (icomplete--field-string))
336 (text (while-no-input
337 (icomplete-completions
338 field-string
339 (icomplete--completion-table)
340 (icomplete--completion-predicate)
341 (if (window-minibuffer-p)
342 (not minibuffer-completion-confirm)))))
343 (buffer-undo-list t)
344 deactivate-mark)
345 ;; Do nothing if while-no-input was aborted.
346 (when (stringp text)
347 (move-overlay icomplete-overlay (point) (point) (current-buffer))
348 ;; The current C cursor code doesn't know to use the overlay's
349 ;; marker's stickiness to figure out whether to place the cursor
350 ;; before or after the string, so let's spoon-feed it the pos.
351 (put-text-property 0 1 'cursor t text)
352 (overlay-put icomplete-overlay 'after-string text)))))))
354 ;;;_ > icomplete-completions (name candidates predicate require-match)
355 (defun icomplete-completions (name candidates predicate require-match)
356 "Identify prospective candidates for minibuffer completion.
358 The display is updated with each minibuffer keystroke during
359 minibuffer completion.
361 Prospective completion suffixes (if any) are displayed, bracketed by
362 one of (), [], or {} pairs. The choice of brackets is as follows:
364 (...) - a single prospect is identified and matching is enforced,
365 [...] - a single prospect is identified but matching is optional, or
366 {...} - multiple prospects, separated by commas, are indicated, and
367 further input is required to distinguish a single one.
369 If there are multiple possibilities, `icomplete-separator' separates them.
371 The displays for unambiguous matches have ` [Matched]' appended
372 \(whether complete or not), or ` [No matches]', if no eligible
373 matches exist."
374 (let* ((minibuffer-completion-table candidates)
375 (minibuffer-completion-predicate predicate)
376 (md (completion--field-metadata (icomplete--field-beg)))
377 (comps (completion-all-sorted-completions
378 (icomplete--field-beg) (icomplete--field-end)))
379 (last (if (consp comps) (last comps)))
380 (base-size (cdr last))
381 (open-bracket (if require-match "(" "["))
382 (close-bracket (if require-match ")" "]")))
383 ;; `concat'/`mapconcat' is the slow part.
384 (if (not (consp comps))
385 (progn ;;(debug (format "Candidates=%S field=%S" candidates name))
386 (format " %sNo matches%s" open-bracket close-bracket))
387 (if last (setcdr last nil))
388 (when (and minibuffer-completing-file-name
389 icomplete-with-completion-tables)
390 (setq comps (completion-pcm--filename-try-filter comps)))
391 (let* ((most-try
392 (if (and base-size (> base-size 0))
393 (completion-try-completion
394 name candidates predicate (length name) md)
395 ;; If the `comps' are 0-based, the result should be
396 ;; the same with `comps'.
397 (completion-try-completion
398 name comps nil (length name) md)))
399 (most (if (consp most-try) (car most-try)
400 (if most-try (car comps) "")))
401 ;; Compare name and most, so we can determine if name is
402 ;; a prefix of most, or something else.
403 (compare (compare-strings name nil nil
404 most nil nil completion-ignore-case))
405 (ellipsis (if (char-displayable-p ?…) "…" "..."))
406 (determ (unless (or (eq t compare) (eq t most-try)
407 (= (setq compare (1- (abs compare)))
408 (length most)))
409 (concat open-bracket
410 (cond
411 ((= compare (length name))
412 ;; Typical case: name is a prefix.
413 (substring most compare))
414 ;; Don't bother truncating if it doesn't gain
415 ;; us at least 2 columns.
416 ((< compare (+ 2 (string-width ellipsis))) most)
417 (t (concat ellipsis (substring most compare))))
418 close-bracket)))
419 ;;"-prospects" - more than one candidate
420 (prospects-len (+ (string-width
421 (or determ (concat open-bracket close-bracket)))
422 (string-width icomplete-separator)
423 (+ 2 (string-width ellipsis)) ;; take {…} into account
424 (string-width (buffer-string))))
425 (prospects-max
426 ;; Max total length to use, including the minibuffer content.
427 (* (+ icomplete-prospects-height
428 ;; If the minibuffer content already uses up more than
429 ;; one line, increase the allowable space accordingly.
430 (/ prospects-len (window-width)))
431 (window-width)))
432 ;; Find the common prefix among `comps'.
433 ;; We can't use the optimization below because its assumptions
434 ;; aren't always true, e.g. when completion-cycling (bug#10850):
435 ;; (if (eq t (compare-strings (car comps) nil (length most)
436 ;; most nil nil completion-ignore-case))
437 ;; ;; Common case.
438 ;; (length most)
439 ;; Else, use try-completion.
440 (prefix (when icomplete-hide-common-prefix
441 (try-completion "" comps)))
442 (prefix-len
443 (and (stringp prefix)
444 ;; Only hide the prefix if the corresponding info
445 ;; is already displayed via `most'.
446 (string-prefix-p prefix most t)
447 (length prefix))) ;;)
448 prospects comp limit)
449 (if (or (eq most-try t) (not (consp (cdr comps))))
450 (setq prospects nil)
451 (when (member name comps)
452 ;; NAME is complete but not unique. This scenario poses
453 ;; following UI issues:
455 ;; - When `icomplete-hide-common-prefix' is non-nil, NAME
456 ;; is stripped empty. This would make the entry
457 ;; inconspicuous.
459 ;; - Due to sorting of completions, NAME may not be the
460 ;; first of the prospects and could be hidden deep in
461 ;; the displayed string.
463 ;; - Because of `icomplete-prospects-height' , NAME may
464 ;; not even be displayed to the user.
466 ;; To circumvent all the above problems, provide a visual
467 ;; cue to the user via an "empty string" in the try
468 ;; completion field.
469 (setq determ (concat open-bracket "" close-bracket)))
470 ;; Compute prospects for display.
471 (while (and comps (not limit))
472 (setq comp
473 (if prefix-len (substring (car comps) prefix-len) (car comps))
474 comps (cdr comps))
475 (setq prospects-len
476 (+ (string-width comp)
477 (string-width icomplete-separator)
478 prospects-len))
479 (if (< prospects-len prospects-max)
480 (push comp prospects)
481 (setq limit t))))
482 (setq prospects (nreverse prospects))
483 ;; Decorate first of the prospects.
484 (when prospects
485 (let ((first (copy-sequence (pop prospects))))
486 (put-text-property 0 (length first)
487 'face 'icomplete-first-match first)
488 (push first prospects)))
489 ;; Restore the base-size info, since completion-all-sorted-completions
490 ;; is cached.
491 (if last (setcdr last base-size))
492 (if prospects
493 (concat determ
495 (mapconcat 'identity prospects icomplete-separator)
496 (and limit (concat icomplete-separator ellipsis))
497 "}")
498 (concat determ " [Matched]"))))))
500 ;;; Iswitchb compatibility
502 ;; We moved Iswitchb to `obsolete' in 24.4, but autoloads in files in
503 ;; `obsolete' aren't obeyed (since that would encourage people to keep using
504 ;; those packages, oblivious to their obsolescence). Given the fact that
505 ;; Iswitchb was very popular, we decided to keep its autoload for a bit longer,
506 ;; so we moved it here.
508 ;;;###autoload(when (locate-library "obsolete/iswitchb")
509 ;;;###autoload (autoload 'iswitchb-mode "iswitchb" "Toggle Iswitchb mode." t)
510 ;;;###autoload (make-obsolete 'iswitchb-mode
511 ;;;###autoload "use `icomplete-mode' or `ido-mode' instead." "24.4"))
513 ;;;_* Provide
514 (provide 'icomplete)
516 ;;_* Local emacs vars.
517 ;;Local variables:
518 ;;allout-layout: (-2 :)
519 ;;End:
521 ;;; icomplete.el ends here