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