[bpt/emacs.git] / lisp / icomplete.el

;;; icomplete.el --- minibuffer completion incremental feedback

;; Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc.

;; Author: Ken Manheimer <klm@nist.gov>
;; Maintainer: Ken Manheimer <klm@nist.gov>
;; Created: Mar 1993 klm@nist.gov - first release to usenet
;; Keywords: help, abbrev

;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2, or (at your option)
;; any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING.  If not, write to
;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

;;; Commentary:

;;; Loading this package implements a more fine-grained minibuffer
;;; completion feedback scheme.  Prospective completions are concisely
;;; indicated within the minibuffer itself, with each successive
;;; keystroke.

;;; See 'icomplete-completions' docstring for a description of the
;;; icomplete display format.

;;; See the `icomplete-minibuffer-setup-hook' docstring for a means to
;;; customize icomplete setup for interoperation with other
;;; minibuffer-oriented packages.

;;; To activate icomplete mode, simply load the package.  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.

;;; Thanks to everyone for their suggestions for refinements of this
;;; package.  I particularly have to credit Michael Cook, who
;;; implemented an incremental completion style in his 'iswitch'
;;; functions that served as a model for icomplete.  Some other
;;; contributors: Noah Freidman (restructuring as minor mode), Colin
;;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and
;;; others.

;;; klm.

;;; Code:

;;;_* Provide
(provide 'icomplete)

;;;_* User Customization variables

;;;_* Initialization
;;;_  = icomplete-minibuffer-setup-hook
(defvar icomplete-minibuffer-setup-hook nil
  "*Icomplete-specific customization of minibuffer setup.

This hook is run during minibuffer setup iff icomplete will be active.
It is intended for use in customizing icomplete for interoperation
with other packages.  For instance:

  \(add-hook 'icomplete-minibuffer-setup-hook 
	    \(function
	     \(lambda ()
	       \(make-local-variable 'resize-minibuffer-window-max-height)
	       \(setq resize-minibuffer-window-max-height 3))))

will constrain rsz-mini to a maximum minibuffer height of 3 lines when
icompletion is occurring.")

;;;_ + Internal Variables
;;;_  = icomplete-mode
(defvar icomplete-mode t
  "Non-nil enables incremental minibuffer completion, once
`\\[icomplete-mode]' function has set things up.")
;;;_  = icomplete-eoinput 1
(defvar icomplete-eoinput 1
  "Point where minibuffer input ends and completion info begins.")
(make-variable-buffer-local 'icomplete-eoinput)
;;;_  = icomplete-pre-command-hook
(defvar icomplete-pre-command-hook nil
  "Incremental-minibuffer-completion pre-command-hook.

Is run in minibuffer before user input when `icomplete-mode' is non-nil.
Use `icomplete-mode' function to set it up properly for incremental
minibuffer completion.")
(add-hook 'icomplete-pre-command-hook 'icomplete-tidy)
;;;_  = icomplete-post-command-hook
(defvar icomplete-post-command-hook nil
  "Incremental-minibuffer-completion post-command-hook.

Is run in minibuffer after user input when `icomplete-mode' is non-nil.
Use `icomplete-mode' function to set it up properly for incremental
minibuffer completion.")
(add-hook 'icomplete-post-command-hook 'icomplete-exhibit)

;;;_ > icomplete-mode (&optional prefix)
;;;###autoload
(defun icomplete-mode (&optional prefix)
  "Activate incremental minibuffer completion for this emacs session,
or deactivate with negative prefix arg."
  (interactive "p")
  (or prefix (setq prefix 0))
  (cond ((>= prefix 0)
	 (setq icomplete-mode t)
	 ;; The following is not really necessary after first time -
	 ;; no great loss.
	 (add-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup))
	(t (setq icomplete-mode nil))))

;;;_ > icomplete-simple-completing-p ()
(defun icomplete-simple-completing-p ()

  "Non-nil if current window is minibuffer that's doing simple completion.

Conditions are:
   the selected window is a minibuffer,
   and not in the middle of macro execution,
   and minibuffer-completion-table is not a symbol (which would
       indicate some non-standard, non-simple completion mechansm,
       like file-name and other custom-func completions)."

  (and (window-minibuffer-p (selected-window))
       (not executing-macro)
       (not (symbolp minibuffer-completion-table))))

;;;_ > icomplete-minibuffer-setup ()
;;;###autoload
(defun icomplete-minibuffer-setup ()
  "Run in minibuffer on activation to establish incremental completion.
Usually run by inclusion in `minibuffer-setup-hook'."
  (cond ((and icomplete-mode (icomplete-simple-completing-p))
	 (make-local-hook 'pre-command-hook)
	 (add-hook 'pre-command-hook
		   (function (lambda ()
			       (run-hooks 'icomplete-pre-command-hook)))
		   nil t)
	 (make-local-hook 'post-command-hook)
	 (add-hook 'post-command-hook
		   (function (lambda ()
			       (run-hooks 'icomplete-post-command-hook)))
		   nil t)
	 (run-hooks 'icomplete-minibuffer-setup-hook))))
\f
;;;_* Completion

;;;_ > 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'."
  (if (icomplete-simple-completing-p)
      (if (and (boundp 'icomplete-eoinput)
	       icomplete-eoinput)

	  (if (> icomplete-eoinput (point-max))
	      ;; Oops, got rug pulled out from under us - reinit:
	      (setq icomplete-eoinput (point-max))
	    (let ((buffer-undo-list buffer-undo-list )) ; prevent entry
	      (delete-region icomplete-eoinput (point-max))))

	;; Reestablish the local variable 'cause minibuffer-setup is weird:
	(make-local-variable 'icomplete-eoinput)
	(setq icomplete-eoinput 1))))

;;;_ > icomplete-exhibit ()
(defun icomplete-exhibit ()
  "Insert icomplete completions display.
Should be run via minibuffer `post-command-hook'.  See `icomplete-mode'
and `minibuffer-setup-hook'."
  (if (icomplete-simple-completing-p)
      (let ((contents (buffer-substring (point-min)(point-max)))
	    (buffer-undo-list t))
	(save-excursion
	  (goto-char (point-max))
                                        ; Register the end of input, so we
                                        ; know where the extra stuff
                                        ; (match-status info) begins:
	  (if (not (boundp 'icomplete-eoinput))
	      ;; In case it got wiped out by major mode business:
	      (make-local-variable 'icomplete-eoinput))
	  (setq icomplete-eoinput (point))
                                        ; Insert the match-status information:
	  (if (> (point-max) 1)
	      (insert-string
	       (icomplete-completions contents
				      minibuffer-completion-table
				      minibuffer-completion-predicate
				      (not
				       minibuffer-completion-confirm))))))))

;;;_ > icomplete-completions (name candidates predicate require-match)
(defun icomplete-completions (name candidates predicate require-match)
  "Identify prospective candidates for minibuffer completion.

The display is updated with each minibuffer keystroke during
minibuffer completion.

Prospective completion suffixes (if any) are displayed, bracketed by
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
          further input is required to distingish a single one.

The displays for disambiguous matches have ` [Matched]' appended
\(whether complete or not), or ` \[No matches]', if no eligible
matches exist."

  (let ((comps (all-completions name candidates predicate))
                                        ; "-determined" - only one candidate
        (open-bracket-determined (if require-match "(" "["))
        (close-bracket-determined (if require-match ")" "]"))
                                        ;"-prospects" - more than one candidate
        (open-bracket-prospects "{")
        (close-bracket-prospects "}")
        )
    (cond ((null comps) (format " %sNo matches%s"
                                open-bracket-determined
                                close-bracket-determined))
          ((null (cdr comps))           ;one match
           (concat (if (and (> (length (car comps))
                               (length name)))
                       (concat open-bracket-determined
                               (substring (car comps) (length name))
                               close-bracket-determined)
                     "")
                   " [Matched]"))
          (t                            ;multiple matches
           (let* ((most (try-completion name candidates predicate))
                  (most-len (length most))
                  most-is-exact
                  (alternatives
                   (apply
                    (function concat)
                    (cdr (apply
			  (function nconc)
			  (mapcar '(lambda (com)
				     (if (= (length com) most-len)
					 ;; Most is one exact match,
					 ;; note that and leave out
					 ;; for later indication:
					 (progn
					   (setq most-is-exact t)
					   ())
				       (list ","
					     (substring com
							most-len))))
				  comps))))))
             (concat (and (> most-len (length name))
                          (concat open-bracket-determined
                                  (substring most (length name))
                                  close-bracket-determined))
                     open-bracket-prospects
                     (if most-is-exact
                         (concat "," alternatives)
                       alternatives)
                     close-bracket-prospects))))))

;;;_ + Initialization
;;; If user hasn't setq-default icomplete-mode to nil, then setup for
;;; activation:
(if icomplete-mode
    (icomplete-mode))


;;;_* Local emacs vars.
;;;Local variables:
;;;outline-layout: (-2 :)
;;;End:

;;; icomplete.el ends here
Commit	Line	Data
be010748	1	;;; icomplete.el --- minibuffer completion incremental feedback
239c87a1	2
be010748	3	;; Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc.
d462ff97	4
be010748 RS	5	;; Author: Ken Manheimer <klm@nist.gov>
	6	;; Maintainer: Ken Manheimer <klm@nist.gov>
	7	;; Created: Mar 1993 klm@nist.gov - first release to usenet
	8	;; Keywords: help, abbrev
d462ff97	9
239c87a1	10	;; This file is part of GNU Emacs.
d462ff97	11
239c87a1 RS	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)
	15	;; any later version.
d462ff97	16
239c87a1 RS	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.
c89164c5	21
239c87a1 RS	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
	24	;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
d462ff97	25
239c87a1	26	;;; Commentary:
d462ff97	27
239c87a1 RS	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
	33	;;; See 'icomplete-completions' docstring for a description of the
	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
	40	;;; To activate icomplete mode, simply load the package. You can
	41	;;; subsequently deactivate it by invoking the function icomplete-mode
	42	;;; with a negative prefix-arg (C-U -1 ESC-x icomplete-mode). Also,
	43	;;; you can prevent activation of the mode during package load by
	44	;;; first setting the variable `icomplete-mode' to nil. Icompletion
	45	;;; can be enabled any time after the package is loaded by invoking
	46	;;; icomplete-mode without a prefix arg.
	47
239c87a1 RS	48	;;; Thanks to everyone for their suggestions for refinements of this
	49	;;; package. I particularly have to credit Michael Cook, who
	50	;;; implemented an incremental completion style in his 'iswitch'
	51	;;; functions that served as a model for icomplete. Some other
	52	;;; contributors: Noah Freidman (restructuring as minor mode), Colin
	53	;;; Rafferty (lemacs reconciliation), Lars Lindberg, RMS, and
	54	;;; others.
	55
	56	;;; klm.
c89164c5	57
239c87a1 RS	58	;;; Code:
	59
	60	;;;_* Provide
d462ff97 RS	61	(provide 'icomplete)
d462ff97 RS	62
239c87a1 RS	63	;;;_* User Customization variables
	64
	65	;;;_* Initialization
	66	;;;_ = icomplete-minibuffer-setup-hook
	67	(defvar icomplete-minibuffer-setup-hook nil
	68	"*Icomplete-specific customization of minibuffer setup.
	69
	70	This hook is run during minibuffer setup iff icomplete will be active.
	71	It is intended for use in customizing icomplete for interoperation
	72	with other packages. For instance:
	73
	74	\(add-hook 'icomplete-minibuffer-setup-hook
	75	\(function
	76	\(lambda ()
	77	\(make-local-variable 'resize-minibuffer-window-max-height)
	78	\(setq resize-minibuffer-window-max-height 3))))
	79
	80	will constrain rsz-mini to a maximum minibuffer height of 3 lines when
	81	icompletion is occurring.")
d462ff97	82
c89164c5	83	;;;_ + Internal Variables
239c87a1 RS	84	;;;_ = icomplete-mode
	85	(defvar icomplete-mode t
	86	"Non-nil enables incremental minibuffer completion, once
	87	`\\[icomplete-mode]' function has set things up.")
c89164c5	88	;;;_ = icomplete-eoinput 1
d462ff97 RS	89	(defvar icomplete-eoinput 1
	90	"Point where minibuffer input ends and completion info begins.")
	91	(make-variable-buffer-local 'icomplete-eoinput)
239c87a1 RS	92	;;;_ = icomplete-pre-command-hook
	93	(defvar icomplete-pre-command-hook nil
	94	"Incremental-minibuffer-completion pre-command-hook.
	95
	96	Is run in minibuffer before user input when `icomplete-mode' is non-nil.
	97	Use `icomplete-mode' function to set it up properly for incremental
	98	minibuffer completion.")
	99	(add-hook 'icomplete-pre-command-hook 'icomplete-tidy)
	100	;;;_ = icomplete-post-command-hook
	101	(defvar icomplete-post-command-hook nil
	102	"Incremental-minibuffer-completion post-command-hook.
	103
	104	Is run in minibuffer after user input when `icomplete-mode' is non-nil.
	105	Use `icomplete-mode' function to set it up properly for incremental
	106	minibuffer completion.")
	107	(add-hook 'icomplete-post-command-hook 'icomplete-exhibit)
	108
	109	;;;_ > icomplete-mode (&optional prefix)
c89164c5	110	;;;###autoload
239c87a1 RS	111	(defun icomplete-mode (&optional prefix)
	112	"Activate incremental minibuffer completion for this emacs session,
	113	or deactivate with negative prefix arg."
	114	(interactive "p")
	115	(or prefix (setq prefix 0))
	116	(cond ((>= prefix 0)
	117	(setq icomplete-mode t)
	118	;; The following is not really necessary after first time -
	119	;; no great loss.
	120	(add-hook 'minibuffer-setup-hook 'icomplete-minibuffer-setup))
	121	(t (setq icomplete-mode nil))))
	122
	123	;;;_ > icomplete-simple-completing-p ()
	124	(defun icomplete-simple-completing-p ()
	125
	126	"Non-nil if current window is minibuffer that's doing simple completion.
	127
	128	Conditions are:
	129	the selected window is a minibuffer,
	130	and not in the middle of macro execution,
	131	and minibuffer-completion-table is not a symbol (which would
	132	indicate some non-standard, non-simple completion mechansm,
	133	like file-name and other custom-func completions)."
	134
	135	(and (window-minibuffer-p (selected-window))
	136	(not executing-macro)
	137	(not (symbolp minibuffer-completion-table))))
d183f322	138
239c87a1 RS	139	;;;_ > icomplete-minibuffer-setup ()
	140	;;;###autoload
	141	(defun icomplete-minibuffer-setup ()
239c87a1	142	"Run in minibuffer on activation to establish incremental completion.
d183f322	143	Usually run by inclusion in `minibuffer-setup-hook'."
239c87a1	144	(cond ((and icomplete-mode (icomplete-simple-completing-p))
d183f322	145	(make-local-hook 'pre-command-hook)
239c87a1 RS	146	(add-hook 'pre-command-hook
239c87a1 RS	147	(function (lambda ()
d183f322 RS	148	(run-hooks 'icomplete-pre-command-hook)))
	149	nil t)
	150	(make-local-hook 'post-command-hook)
239c87a1 RS	151	(add-hook 'post-command-hook
239c87a1 RS	152	(function (lambda ()
d183f322 RS	153	(run-hooks 'icomplete-post-command-hook)))
d183f322 RS	154	nil t)
239c87a1	155	(run-hooks 'icomplete-minibuffer-setup-hook))))
d183f322	156	\f
239c87a1 RS	157	;;;_* Completion
	158
	159	;;;_ > icomplete-tidy ()
	160	(defun icomplete-tidy ()
	161	"Remove completions display \(if any) prior to new user input.
d183f322	162	Should be run in on the minibuffer `pre-command-hook'. See `icomplete-mode'
239c87a1 RS	163	and `minibuffer-setup-hook'."
239c87a1 RS	164	(if (icomplete-simple-completing-p)
d462ff97 RS	165	(if (and (boundp 'icomplete-eoinput)
d462ff97 RS	166	icomplete-eoinput)
239c87a1	167
d462ff97 RS	168	(if (> icomplete-eoinput (point-max))
	169	;; Oops, got rug pulled out from under us - reinit:
	170	(setq icomplete-eoinput (point-max))
c89164c5	171	(let ((buffer-undo-list buffer-undo-list )) ; prevent entry
d462ff97	172	(delete-region icomplete-eoinput (point-max))))
239c87a1	173
c89164c5	174	;; Reestablish the local variable 'cause minibuffer-setup is weird:
d462ff97 RS	175	(make-local-variable 'icomplete-eoinput)
d462ff97 RS	176	(setq icomplete-eoinput 1))))
d183f322	177
239c87a1	178	;;;_ > icomplete-exhibit ()
d462ff97	179	(defun icomplete-exhibit ()
239c87a1	180	"Insert icomplete completions display.
d183f322	181	Should be run via minibuffer `post-command-hook'. See `icomplete-mode'
239c87a1 RS	182	and `minibuffer-setup-hook'."
239c87a1 RS	183	(if (icomplete-simple-completing-p)
d462ff97 RS	184	(let ((contents (buffer-substring (point-min)(point-max)))
	185	(buffer-undo-list t))
	186	(save-excursion
	187	(goto-char (point-max))
	188	; Register the end of input, so we
	189	; know where the extra stuff
	190	; (match-status info) begins:
	191	(if (not (boundp 'icomplete-eoinput))
	192	;; In case it got wiped out by major mode business:
	193	(make-local-variable 'icomplete-eoinput))
	194	(setq icomplete-eoinput (point))
	195	; Insert the match-status information:
	196	(if (> (point-max) 1)
	197	(insert-string
239c87a1 RS	198	(icomplete-completions contents
	199	minibuffer-completion-table
	200	minibuffer-completion-predicate
	201	(not
	202	minibuffer-completion-confirm))))))))
d183f322	203
239c87a1 RS	204	;;;_ > icomplete-completions (name candidates predicate require-match)
239c87a1 RS	205	(defun icomplete-completions (name candidates predicate require-match)
d462ff97 RS	206	"Identify prospective candidates for minibuffer completion.
d462ff97 RS	207
c89164c5	208	The display is updated with each minibuffer keystroke during
d462ff97 RS	209	minibuffer completion.
	210
	211	Prospective completion suffixes (if any) are displayed, bracketed by
	212	one of \(), \[], or \{} pairs. The choice of brackets is as follows:
	213
	214	\(...) - a single prospect is identified and matching is enforced,
	215	\[...] - a single prospect is identified but matching is optional, or
	216	\{...} - multiple prospects, separated by commas, are indicated, and
	217	further input is required to distingish a single one.
	218
d183f322 RS	219	The displays for disambiguous matches have ` [Matched]' appended
d183f322 RS	220	\(whether complete or not), or ` \[No matches]', if no eligible
d462ff97 RS	221	matches exist."
	222
	223	(let ((comps (all-completions name candidates predicate))
	224	; "-determined" - only one candidate
	225	(open-bracket-determined (if require-match "(" "["))
	226	(close-bracket-determined (if require-match ")" "]"))
	227	;"-prospects" - more than one candidate
	228	(open-bracket-prospects "{")
	229	(close-bracket-prospects "}")
	230	)
	231	(cond ((null comps) (format " %sNo matches%s"
	232	open-bracket-determined
	233	close-bracket-determined))
	234	((null (cdr comps)) ;one match
	235	(concat (if (and (> (length (car comps))
	236	(length name)))
	237	(concat open-bracket-determined
	238	(substring (car comps) (length name))
	239	close-bracket-determined)
	240	"")
	241	" [Matched]"))
	242	(t ;multiple matches
	243	(let* ((most (try-completion name candidates predicate))
	244	(most-len (length most))
	245	most-is-exact
	246	(alternatives
	247	(apply
239c87a1 RS	248	(function concat)
	249	(cdr (apply
	250	(function nconc)
	251	(mapcar '(lambda (com)
	252	(if (= (length com) most-len)
	253	;; Most is one exact match,
	254	;; note that and leave out
	255	;; for later indication:
	256	(progn
	257	(setq most-is-exact t)
	258	())
	259	(list ","
	260	(substring com
	261	most-len))))
	262	comps))))))
d462ff97 RS	263	(concat (and (> most-len (length name))
	264	(concat open-bracket-determined
	265	(substring most (length name))
	266	close-bracket-determined))
	267	open-bracket-prospects
	268	(if most-is-exact
	269	(concat "," alternatives)
	270	alternatives)
	271	close-bracket-prospects))))))
	272
239c87a1 RS	273	;;;_ + Initialization
	274	;;; If user hasn't setq-default icomplete-mode to nil, then setup for
	275	;;; activation:
	276	(if icomplete-mode
	277	(icomplete-mode))
	278
	279
	280	;;;_* Local emacs vars.
	281	;;;Local variables:
	282	;;;outline-layout: (-2 :)
	283	;;;End:
d462ff97 RS	284
d462ff97 RS	285	;;; icomplete.el ends here
c89164c5	286