[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-variable 'pre-command-hook)
	 (setq pre-command-hook (copy-sequence pre-command-hook))
	 (add-hook 'pre-command-hook
		   (function (lambda ()
			       (run-hooks 'icomplete-pre-command-hook))))
	 (make-local-variable 'post-command-hook)
	 (setq post-command-hook (copy-sequence post-command-hook))
	 (add-hook 'post-command-hook
		   (function (lambda ()
			       (run-hooks 'icomplete-post-command-hook))))
	 (run-hooks 'icomplete-minibuffer-setup-hook))))

;;;_* 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))))
	139	;;;_ > icomplete-minibuffer-setup ()
	140	;;;###autoload
	141	(defun icomplete-minibuffer-setup ()
	142
	143	"Run in minibuffer on activation to establish incremental completion.
	144
	145	Usually run by inclusion in minibuffer-setup-hook."
	146
	147	(cond ((and icomplete-mode (icomplete-simple-completing-p))
	148	(make-local-variable 'pre-command-hook)
	149	(setq pre-command-hook (copy-sequence pre-command-hook))
	150	(add-hook 'pre-command-hook
	151	(function (lambda ()
	152	(run-hooks 'icomplete-pre-command-hook))))
	153	(make-local-variable 'post-command-hook)
	154	(setq post-command-hook (copy-sequence post-command-hook))
	155	(add-hook 'post-command-hook
	156	(function (lambda ()
	157	(run-hooks 'icomplete-post-command-hook))))
	158	(run-hooks 'icomplete-minibuffer-setup-hook))))
	159
	160	;;;_* Completion
	161
	162	;;;_ > icomplete-tidy ()
	163	(defun icomplete-tidy ()
	164	"Remove completions display \(if any) prior to new user input.
	165
	166	Should be run in on the minibuffer pre-command-hook. See `icomplete-mode'
	167	and `minibuffer-setup-hook'."
	168	(if (icomplete-simple-completing-p)
d462ff97 RS	169	(if (and (boundp 'icomplete-eoinput)
d462ff97 RS	170	icomplete-eoinput)
239c87a1	171
d462ff97 RS	172	(if (> icomplete-eoinput (point-max))
	173	;; Oops, got rug pulled out from under us - reinit:
	174	(setq icomplete-eoinput (point-max))
c89164c5	175	(let ((buffer-undo-list buffer-undo-list )) ; prevent entry
d462ff97	176	(delete-region icomplete-eoinput (point-max))))
239c87a1	177
c89164c5	178	;; Reestablish the local variable 'cause minibuffer-setup is weird:
d462ff97 RS	179	(make-local-variable 'icomplete-eoinput)
d462ff97 RS	180	(setq icomplete-eoinput 1))))
239c87a1	181	;;;_ > icomplete-exhibit ()
d462ff97	182	(defun icomplete-exhibit ()
239c87a1 RS	183	"Insert icomplete completions display.
	184
	185	Should be run via minibuffer post-command-hook. See `icomplete-mode'
	186	and `minibuffer-setup-hook'."
	187	(if (icomplete-simple-completing-p)
d462ff97 RS	188	(let ((contents (buffer-substring (point-min)(point-max)))
	189	(buffer-undo-list t))
	190	(save-excursion
	191	(goto-char (point-max))
	192	; Register the end of input, so we
	193	; know where the extra stuff
	194	; (match-status info) begins:
	195	(if (not (boundp 'icomplete-eoinput))
	196	;; In case it got wiped out by major mode business:
	197	(make-local-variable 'icomplete-eoinput))
	198	(setq icomplete-eoinput (point))
	199	; Insert the match-status information:
	200	(if (> (point-max) 1)
	201	(insert-string
239c87a1 RS	202	(icomplete-completions contents
	203	minibuffer-completion-table
	204	minibuffer-completion-predicate
	205	(not
	206	minibuffer-completion-confirm))))))))
	207	;;;_ > icomplete-completions (name candidates predicate require-match)
	208	(defun icomplete-completions (name candidates predicate require-match)
d462ff97 RS	209	"Identify prospective candidates for minibuffer completion.
d462ff97 RS	210
c89164c5	211	The display is updated with each minibuffer keystroke during
d462ff97 RS	212	minibuffer completion.
	213
	214	Prospective completion suffixes (if any) are displayed, bracketed by
	215	one of \(), \[], or \{} pairs. The choice of brackets is as follows:
	216
	217	\(...) - a single prospect is identified and matching is enforced,
	218	\[...] - a single prospect is identified but matching is optional, or
	219	\{...} - multiple prospects, separated by commas, are indicated, and
	220	further input is required to distingish a single one.
	221
	222	The displays for disambiguous matches have \" [Matched]\" appended
	223	\(whether complete or not), or \" \[No matches]\", if no eligible
	224	matches exist."
	225
	226	(let ((comps (all-completions name candidates predicate))
	227	; "-determined" - only one candidate
	228	(open-bracket-determined (if require-match "(" "["))
	229	(close-bracket-determined (if require-match ")" "]"))
	230	;"-prospects" - more than one candidate
	231	(open-bracket-prospects "{")
	232	(close-bracket-prospects "}")
	233	)
	234	(cond ((null comps) (format " %sNo matches%s"
	235	open-bracket-determined
	236	close-bracket-determined))
	237	((null (cdr comps)) ;one match
	238	(concat (if (and (> (length (car comps))
	239	(length name)))
	240	(concat open-bracket-determined
	241	(substring (car comps) (length name))
	242	close-bracket-determined)
	243	"")
	244	" [Matched]"))
	245	(t ;multiple matches
	246	(let* ((most (try-completion name candidates predicate))
	247	(most-len (length most))
	248	most-is-exact
	249	(alternatives
	250	(apply
239c87a1 RS	251	(function concat)
	252	(cdr (apply
	253	(function nconc)
	254	(mapcar '(lambda (com)
	255	(if (= (length com) most-len)
	256	;; Most is one exact match,
	257	;; note that and leave out
	258	;; for later indication:
	259	(progn
	260	(setq most-is-exact t)
	261	())
	262	(list ","
	263	(substring com
	264	most-len))))
	265	comps))))))
d462ff97 RS	266	(concat (and (> most-len (length name))
	267	(concat open-bracket-determined
	268	(substring most (length name))
	269	close-bracket-determined))
	270	open-bracket-prospects
	271	(if most-is-exact
	272	(concat "," alternatives)
	273	alternatives)
	274	close-bracket-prospects))))))
	275
239c87a1 RS	276	;;;_ + Initialization
	277	;;; If user hasn't setq-default icomplete-mode to nil, then setup for
	278	;;; activation:
	279	(if icomplete-mode
	280	(icomplete-mode))
	281
	282
	283	;;;_* Local emacs vars.
	284	;;;Local variables:
	285	;;;outline-layout: (-2 :)
	286	;;;End:
d462ff97 RS	287
d462ff97 RS	288	;;; icomplete.el ends here
c89164c5	289