;;; icomplete.el --- minibuffer completion incremental feedback
-;; Copyright (C) 1992-1994, 1997, 1999, 2001-2013 Free Software
-;; Foundation, Inc.
+;; Copyright (C) 1992-1994, 1997, 1999, 2001-2014
+;; Free Software Foundation, Inc.
;; Author: Ken Manheimer <klm@i.am>
;; Maintainer: Ken Manheimer <klm@i.am>
;; Created: Mar 1993 Ken Manheimer, klm@nist.gov - first release to usenet
-;; Last update: Ken Manheimer <klm@i.am>, 11/18/1999.
;; Keywords: help, abbrev
;; This file is part of GNU Emacs.
;;; Commentary:
-;; Loading this package implements a more fine-grained minibuffer
+;; Enabling this package implements a more fine-grained minibuffer
;; completion feedback scheme. Prospective completions are concisely
;; indicated within the minibuffer itself, with each successive
;; keystroke.
;; customize icomplete setup for interoperation with other
;; minibuffer-oriented packages.
-;; To activate icomplete mode, load the package and use the
-;; `icomplete-mode' function. You can subsequently deactivate it by
-;; invoking the function icomplete-mode with a negative prefix-arg
-;; (C-U -1 ESC-x icomplete-mode). Also, you can prevent activation of
-;; the mode during package load by first setting the variable
-;; `icomplete-mode' to nil. Icompletion can be enabled any time after
-;; the package is loaded by invoking icomplete-mode without a prefix
-;; arg.
+;; To enable/disable icomplete mode, use the `icomplete-mode' function.
;; Thanks to everyone for their suggestions for refinements of this
;; package. I particularly have to credit Michael Cook, who
(defgroup icomplete nil
"Show completions dynamically in minibuffer."
:prefix "icomplete-"
+ :link '(info-link "(emacs)Icomplete")
:group 'minibuffer)
(defvar icomplete-prospects-length 80)
'icomplete-prospects-length 'icomplete-prospects-height "23.1")
(defcustom icomplete-separator " | "
- "String used by icomplete to separate alternatives in the minibuffer."
+ "String used by Icomplete to separate alternatives in the minibuffer."
:type 'string
:version "24.4")
:type 'boolean
:version "24.4")
-(defcustom icomplete-show-matches-on-no-input t
+(defcustom icomplete-show-matches-on-no-input nil
"When non-nil, show completions when first prompting for input."
:type 'boolean
:version "24.4")
-(defface icomplete-first-match '((t :weight bold))
- "Face used by icomplete for highlighting first match."
+(defcustom icomplete-with-completion-tables t
+ "Specialized completion tables with which Icomplete should operate.
+If this is t, Icomplete operates on all tables.
+Otherwise this should be a list of the completion tables (e.g.,
+`internal-complete-buffer') on which Icomplete should operate."
+ ;; Prior to 24.4, not a user-option, default '(internal-complete-buffer).
+ :version "24.4"
+ :type '(choice (const :tag "All" t)
+ (repeat function)))
+
+(defface icomplete-first-match '((t :weight bold))
+ "Face used by Icomplete for highlighting first match."
:version "24.4")
;;;_* User Customization variables
:type 'integer)
(defcustom icomplete-max-delay-chars 3
- "Maximum number of initial chars to apply icomplete compute delay."
+ "Maximum number of initial chars to apply `icomplete-compute-delay'."
:type 'integer)
(defvar icomplete-in-buffer nil
(defcustom icomplete-minibuffer-setup-hook nil
"Icomplete-specific customization of minibuffer setup.
-This hook is run during minibuffer setup if icomplete is active.
-It is intended for use in customizing icomplete for interoperation
+This hook is run during minibuffer setup if Icomplete is active.
+It is intended for use in customizing Icomplete for interoperation
with other features and packages. For instance:
- \(add-hook 'icomplete-minibuffer-setup-hook
- \(function
- \(lambda ()
- \(make-local-variable 'max-mini-window-height)
- \(setq max-mini-window-height 3))))
+ (add-hook 'icomplete-minibuffer-setup-hook
+ (lambda () (setq-local max-mini-window-height 3)))
will constrain Emacs to a maximum minibuffer height of 3 lines when
icompletion is occurring."
(let ((non-essential t)) ;E.g. don't prompt for password!
(icomplete-exhibit)))
-;;;_ = icomplete-with-completion-tables
-(defcustom icomplete-with-completion-tables t
- "Specialized completion tables with which icomplete should operate.
-
-Icomplete does not operate with any specialized completion tables
-except those on this list."
- :version "24.4"
- :type '(choice (const :tag "All" t)
- (repeat function)))
-
(defvar icomplete-minibuffer-map
(let ((map (make-sparse-keymap)))
(define-key map [?\M-\t] 'minibuffer-force-complete)
(define-key map [?\C-j] 'minibuffer-force-complete-and-exit)
(define-key map [?\C-.] 'icomplete-forward-completions)
(define-key map [?\C-,] 'icomplete-backward-completions)
- map))
+ map)
+ "Keymap used by `icomplete-mode' in the minibuffer.")
(defun icomplete-forward-completions ()
"Step forward completions by one entry.
"Toggle incremental minibuffer completion (Icomplete mode).
With a prefix argument ARG, enable Icomplete mode if ARG is
positive, and disable it otherwise. If called from Lisp, enable
-the mode if ARG is omitted or nil."
+the mode if ARG is omitted or nil.
+
+When this global minor mode is enabled, typing in the minibuffer
+continuously displays a list of possible completions that match
+the string you have typed. See `icomplete-completions' for a
+description of how prospective completions are displayed.
+
+For more information, see Info node `(emacs)Icomplete'.
+For options you can set, `\\[customize-group] icomplete'.
+
+You can use the following key bindings to navigate and select
+completions:
+
+\\{icomplete-minibuffer-map}"
:global t :group 'icomplete
(remove-hook 'minibuffer-setup-hook #'icomplete-minibuffer-setup)
(remove-hook 'completion-in-region-mode-hook #'icomplete--in-region-setup)
;;;_ > icomplete-simple-completing-p ()
(defun icomplete-simple-completing-p ()
- "Non-nil if current window is minibuffer that's doing simple completion.
+ "Non-nil if current window is a minibuffer that's doing simple completion.
Conditions are:
the selected window is a minibuffer,
and not in the middle of macro execution,
and the completion table is not a function (which would
indicate some non-standard, non-simple completion mechanism,
- like file-name and other custom-func completions)."
+ like file-name and other custom-func completions),
+ and `icomplete-with-completion-tables' doesn't restrict completion."
(unless executing-kbd-macro
(let ((table (icomplete--completion-table)))
;;;_ > icomplete-tidy ()
(defun icomplete-tidy ()
- "Remove completions display \(if any) prior to new user input.
-Should be run in on the minibuffer `pre-command-hook'. See `icomplete-mode'
-and `minibuffer-setup-hook'."
+ "Remove completions display (if any) prior to new user input.
+Should be run in on the minibuffer `pre-command-hook'.
+See `icomplete-mode' and `minibuffer-setup-hook'."
(delete-overlay icomplete-overlay))
;;;_ > icomplete-exhibit ()
(defun icomplete-exhibit ()
- "Insert icomplete completions display.
-Should be run via minibuffer `post-command-hook'. See `icomplete-mode'
-and `minibuffer-setup-hook'."
+ "Insert Icomplete completions display.
+Should be run via minibuffer `post-command-hook'.
+See `icomplete-mode' and `minibuffer-setup-hook'."
(when (and icomplete-mode
(icomplete-simple-completing-p)) ;Shouldn't be necessary.
(save-excursion
minibuffer completion.
Prospective completion suffixes (if any) are displayed, bracketed by
-one of \(), \[], or \{} pairs. The choice of brackets is as follows:
+one of (), [], or {} pairs. The choice of brackets is as follows:
- \(...) - a single prospect is identified and matching is enforced,
- \[...] - a single prospect is identified but matching is optional, or
- \{...} - multiple prospects, separated by commas, are indicated, and
+ (...) - a single prospect is identified and matching is enforced,
+ [...] - a single prospect is identified but matching is optional, or
+ {...} - multiple prospects, separated by commas, are indicated, and
further input is required to distinguish a single one.
-The displays for unambiguous matches have ` [Matched]' appended
-\(whether complete or not), or ` \[No matches]', if no eligible
-matches exist. \(Keybindings for uniquely matched commands
-are exhibited within the square braces.)"
+If there are multiple possibilities, `icomplete-separator' separates them.
+The displays for unambiguous matches have ` [Matched]' appended
+\(whether complete or not), or ` [No matches]', if no eligible
+matches exist."
(let* ((minibuffer-completion-table candidates)
(minibuffer-completion-predicate predicate)
(md (completion--field-metadata (icomplete--field-beg)))
;; a prefix of most, or something else.
(compare (compare-strings name nil nil
most nil nil completion-ignore-case))
+ (ellipsis (if (char-displayable-p ?…) "…" "..."))
(determ (unless (or (eq t compare) (eq t most-try)
(= (setq compare (1- (abs compare)))
(length most)))
(substring most compare))
;; Don't bother truncating if it doesn't gain
;; us at least 2 columns.
- ((< compare 3) most)
- (t (concat "…" (substring most compare))))
+ ((< compare (+ 2 (string-width ellipsis))) most)
+ (t (concat ellipsis (substring most compare))))
close-bracket)))
;;"-prospects" - more than one candidate
(prospects-len (+ (string-width
(or determ (concat open-bracket close-bracket)))
(string-width icomplete-separator)
- 3 ;; take {…} into account
+ (+ 2 (string-width ellipsis)) ;; take {…} into account
(string-width (buffer-string))))
(prospects-max
;; Max total length to use, including the minibuffer content.
(concat determ
"{"
(mapconcat 'identity prospects icomplete-separator)
- (and limit (concat icomplete-separator "…"))
+ (and limit (concat icomplete-separator ellipsis))
"}")
(concat determ " [Matched]"))))))