*** empty log message ***
[emacs.git] / lisp / pcomplete.el
blob3ca88afd30684a13cc85a175a11cde8ac4a33e5f
1 ;;; pcomplete.el --- programmable completion
3 ;; Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004
4 ;; 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
6 ;; Author: John Wiegley <johnw@gnu.org>
7 ;; Keywords: processes abbrev
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software; you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation; either version 3, or (at your option)
14 ;; any later version.
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs; see the file COPYING. If not, write to the
23 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
24 ;; Boston, MA 02110-1301, USA.
26 ;;; Commentary:
28 ;; This module provides a programmable completion facility using
29 ;; "completion functions". Each completion function is responsible
30 ;; for producing a list of possible completions relevant to the current
31 ;; argument position.
33 ;; To use pcomplete with shell-mode, for example, you will need the
34 ;; following in your .emacs file:
36 ;; (add-hook 'shell-mode-hook 'pcomplete-shell-setup)
38 ;; Most of the code below simply provides support mechanisms for
39 ;; writing completion functions. Completion functions themselves are
40 ;; very easy to write. They have few requirements beyond those of
41 ;; regular Lisp functions.
43 ;; Consider the following example, which will complete against
44 ;; filenames for the first two arguments, and directories for all
45 ;; remaining arguments:
47 ;; (defun pcomplete/my-command ()
48 ;; (pcomplete-here (pcomplete-entries))
49 ;; (pcomplete-here (pcomplete-entries))
50 ;; (while (pcomplete-here (pcomplete-dirs))))
52 ;; Here are the requirements for completion functions:
54 ;; @ They must be called "pcomplete/MAJOR-MODE/NAME", or
55 ;; "pcomplete/NAME". This is how they are looked up, using the NAME
56 ;; specified in the command argument (the argument in first
57 ;; position).
59 ;; @ They must be callable with no arguments.
61 ;; @ Their return value is ignored. If they actually return normally,
62 ;; it means no completions were available.
64 ;; @ In order to provide completions, they must throw the tag
65 ;; `pcomplete-completions'. The value must be the list of possible
66 ;; completions for the final argument.
68 ;; @ To simplify completion function logic, the tag `pcompleted' may
69 ;; be thrown with a value of nil in order to abort the function. It
70 ;; means that there were no completions available.
72 ;; When a completion function is called, the variable `pcomplete-args'
73 ;; is in scope, and contains all of the arguments specified on the
74 ;; command line. The variable `pcomplete-last' is the index of the
75 ;; last argument in that list.
77 ;; The variable `pcomplete-index' is used by the completion code to
78 ;; know which argument the completion function is currently examining.
79 ;; It always begins at 1, meaning the first argument after the command
80 ;; name.
82 ;; To facilitate writing completion logic, a special macro,
83 ;; `pcomplete-here', has been provided which does several things:
85 ;; 1. It will throw `pcompleted' (with a value of nil) whenever
86 ;; `pcomplete-index' exceeds `pcomplete-last'.
88 ;; 2. It will increment `pcomplete-index' if the final argument has
89 ;; not been reached yet.
91 ;; 3. It will evaluate the form passed to it, and throw the result
92 ;; using the `pcomplete-completions' tag, if it is called when
93 ;; `pcomplete-index' is pointing to the final argument.
95 ;; Sometimes a completion function will want to vary the possible
96 ;; completions for an argument based on the previous one. To
97 ;; facilitate tests like this, the function `pcomplete-test' and
98 ;; `pcomplete-match' are provided. Called with one argument, they
99 ;; test the value of the previous command argument. Otherwise, a
100 ;; relative index may be given as an optional second argument, where 0
101 ;; refers to the current argument, 1 the previous, 2 the one before
102 ;; that, etc. The symbols `first' and `last' specify absolute
103 ;; offsets.
105 ;; Here is an example which will only complete against directories for
106 ;; the second argument if the first argument is also a directory:
108 ;; (defun pcomplete/example ()
109 ;; (pcomplete-here (pcomplete-entries))
110 ;; (if (pcomplete-test 'file-directory-p)
111 ;; (pcomplete-here (pcomplete-dirs))
112 ;; (pcomplete-here (pcomplete-entries))))
114 ;; For generating completion lists based on directory contents, see
115 ;; the functions `pcomplete-entries', `pcomplete-dirs',
116 ;; `pcomplete-executables' and `pcomplete-all-entries'.
118 ;; Consult the documentation for `pcomplete-here' for information
119 ;; about its other arguments.
121 ;;; Code:
123 (provide 'pcomplete)
125 (defgroup pcomplete nil
126 "Programmable completion."
127 :version "21.1"
128 :group 'processes)
130 ;;; User Variables:
132 (defcustom pcomplete-file-ignore nil
133 "*A regexp of filenames to be disregarded during file completion."
134 :type '(choice regexp (const :tag "None" nil))
135 :group 'pcomplete)
137 (defcustom pcomplete-dir-ignore nil
138 "*A regexp of names to be disregarded during directory completion."
139 :type '(choice regexp (const :tag "None" nil))
140 :group 'pcomplete)
142 (defcustom pcomplete-ignore-case (memq system-type '(ms-dos windows-nt cygwin))
143 "*If non-nil, ignore case when doing filename completion."
144 :type 'boolean
145 :group 'pcomplete)
147 (defcustom pcomplete-autolist nil
148 "*If non-nil, automatically list possibilities on partial completion.
149 This mirrors the optional behavior of tcsh."
150 :type 'boolean
151 :group 'pcomplete)
153 (defcustom pcomplete-suffix-list (list ?/ ?:)
154 "*A list of characters which constitute a proper suffix."
155 :type '(repeat character)
156 :group 'pcomplete)
158 (defcustom pcomplete-recexact nil
159 "*If non-nil, use shortest completion if characters cannot be added.
160 This mirrors the optional behavior of tcsh.
162 A non-nil value is useful if `pcomplete-autolist' is non-nil too."
163 :type 'boolean
164 :group 'pcomplete)
166 (defcustom pcomplete-arg-quote-list nil
167 "*List of characters to quote when completing an argument."
168 :type '(choice (repeat character)
169 (const :tag "Don't quote" nil))
170 :group 'pcomplete)
172 (defcustom pcomplete-quote-arg-hook nil
173 "*A hook which is run to quote a character within a filename.
174 Each function is passed both the filename to be quoted, and the index
175 to be considered. If the function wishes to provide an alternate
176 quoted form, it need only return the replacement string. If no
177 function provides a replacement, quoting shall proceed as normal,
178 using a backslash to quote any character which is a member of
179 `pcomplete-arg-quote-list'."
180 :type 'hook
181 :group 'pcomplete)
183 (defcustom pcomplete-man-function 'man
184 "*A function to that will be called to display a manual page.
185 It will be passed the name of the command to document."
186 :type 'function
187 :group 'pcomplete)
189 (defcustom pcomplete-compare-entry-function 'string-lessp
190 "*This function is used to order file entries for completion.
191 The behavior of most all shells is to sort alphabetically."
192 :type '(radio (function-item string-lessp)
193 (function-item file-newer-than-file-p)
194 (function :tag "Other"))
195 :group 'pcomplete)
197 (defcustom pcomplete-help nil
198 "*A string or function (or nil) used for context-sensitive help.
199 If a string, it should name an Info node that will be jumped to.
200 If non-nil, it must a sexp that will be evaluated, and whose
201 result will be shown in the minibuffer.
202 If nil, the function `pcomplete-man-function' will be called with the
203 current command argument."
204 :type '(choice string sexp (const :tag "Use man page" nil))
205 :group 'pcomplete)
207 (defcustom pcomplete-expand-before-complete nil
208 "*If non-nil, expand the current argument before completing it.
209 This means that typing something such as '$HOME/bi' followed by
210 \\[pcomplete-argument] will cause the variable reference to be
211 resolved first, and the resultant value that will be completed against
212 to be inserted in the buffer. Note that exactly what gets expanded
213 and how is entirely up to the behavior of the
214 `pcomplete-parse-arguments-function'."
215 :type 'boolean
216 :group 'pcomplete)
218 (defcustom pcomplete-parse-arguments-function
219 'pcomplete-parse-buffer-arguments
220 "*A function to call to parse the current line's arguments.
221 It should be called with no parameters, and with point at the position
222 of the argument that is to be completed.
224 It must either return nil, or a cons cell of the form:
226 ((ARG...) (BEG-POS...))
228 The two lists must be identical in length. The first gives the final
229 value of each command line argument (which need not match the textual
230 representation of that argument), and BEG-POS gives the beginning
231 position of each argument, as it is seen by the user. The establishes
232 a relationship between the fully resolved value of the argument, and
233 the textual representation of the argument."
234 :type 'function
235 :group 'pcomplete)
237 (defcustom pcomplete-cycle-completions t
238 "*If non-nil, hitting the TAB key cycles through the completion list.
239 Typical Emacs behavior is to complete as much as possible, then pause
240 waiting for further input. Then if TAB is hit again, show a list of
241 possible completions. When `pcomplete-cycle-completions' is non-nil,
242 it acts more like zsh or 4nt, showing the first maximal match first,
243 followed by any further matches on each subsequent pressing of the TAB
244 key. \\[pcomplete-list] is the key to press if the user wants to see
245 the list of possible completions."
246 :type 'boolean
247 :group 'pcomplete)
249 (defcustom pcomplete-cycle-cutoff-length 5
250 "*If the number of completions is greater than this, don't cycle.
251 This variable is a compromise between the traditional Emacs style of
252 completion, and the \"cycling\" style. Basically, if there are more
253 than this number of completions possible, don't automatically pick the
254 first one and then expect the user to press TAB to cycle through them.
255 Typically, when there are a large number of completion possibilities,
256 the user wants to see them in a list buffer so that they can know what
257 options are available. But if the list is small, it means the user
258 has already entered enough input to disambiguate most of the
259 possibilities, and therefore they are probably most interested in
260 cycling through the candidates. Set this value to nil if you want
261 cycling to always be enabled."
262 :type '(choice integer (const :tag "Always cycle" nil))
263 :group 'pcomplete)
265 (defcustom pcomplete-restore-window-delay 1
266 "*The number of seconds to wait before restoring completion windows.
267 Once the completion window has been displayed, if the user then goes
268 on to type something else, that completion window will be removed from
269 the display (actually, the original window configuration before it was
270 displayed will be restored), after this many seconds of idle time. If
271 set to nil, completion windows will be left on second until the user
272 removes them manually. If set to 0, they will disappear immediately
273 after the user enters a key other than TAB."
274 :type '(choice integer (const :tag "Never restore" nil))
275 :group 'pcomplete)
277 (defcustom pcomplete-try-first-hook nil
278 "*A list of functions which are called before completing an argument.
279 This can be used, for example, for completing things which might apply
280 to all arguments, such as variable names after a $."
281 :type 'hook
282 :group 'pcomplete)
284 (defsubst pcomplete-executables (&optional regexp)
285 "Complete amongst a list of directories and executables."
286 (pcomplete-entries regexp 'file-executable-p))
288 (defcustom pcomplete-command-completion-function
289 (function
290 (lambda ()
291 (pcomplete-here (pcomplete-executables))))
292 "*Function called for completing the initial command argument."
293 :type 'function
294 :group 'pcomplete)
296 (defcustom pcomplete-command-name-function 'pcomplete-command-name
297 "*Function called for determining the current command name."
298 :type 'function
299 :group 'pcomplete)
301 (defcustom pcomplete-default-completion-function
302 (function
303 (lambda ()
304 (while (pcomplete-here (pcomplete-entries)))))
305 "*Function called when no completion rule can be found.
306 This function is used to generate completions for every argument."
307 :type 'function
308 :group 'pcomplete)
310 (defcustom pcomplete-use-paring t
311 "*If t, pare alternatives that have already been used.
312 If nil, you will always see the completion set of possible options, no
313 matter which of those options have already been used in previous
314 command arguments."
315 :type 'boolean
316 :group 'pcomplete)
318 (defcustom pcomplete-termination-string " "
319 "*A string that is inserted after any completion or expansion.
320 This is usually a space character, useful when completing lists of
321 words separated by spaces. However, if your list uses a different
322 separator character, or if the completion occurs in a word that is
323 already terminated by a character, this variable should be locally
324 modified to be an empty string, or the desired separation string."
325 :type 'string
326 :group 'pcomplete)
328 ;;; Internal Variables:
330 ;; for cycling completion support
331 (defvar pcomplete-current-completions nil)
332 (defvar pcomplete-last-completion-length)
333 (defvar pcomplete-last-completion-stub)
334 (defvar pcomplete-last-completion-raw)
335 (defvar pcomplete-last-window-config nil)
336 (defvar pcomplete-window-restore-timer nil)
338 (make-variable-buffer-local 'pcomplete-current-completions)
339 (make-variable-buffer-local 'pcomplete-last-completion-length)
340 (make-variable-buffer-local 'pcomplete-last-completion-stub)
341 (make-variable-buffer-local 'pcomplete-last-completion-raw)
342 (make-variable-buffer-local 'pcomplete-last-window-config)
343 (make-variable-buffer-local 'pcomplete-window-restore-timer)
345 ;; used for altering pcomplete's behavior. These global variables
346 ;; should always be nil.
347 (defvar pcomplete-show-help nil)
348 (defvar pcomplete-show-list nil)
349 (defvar pcomplete-expand-only-p nil)
351 ;;; User Functions:
353 ;;;###autoload
354 (defun pcomplete (&optional interactively)
355 "Support extensible programmable completion.
356 To use this function, just bind the TAB key to it, or add it to your
357 completion functions list (it should occur fairly early in the list)."
358 (interactive "p")
359 (if (and interactively
360 pcomplete-cycle-completions
361 pcomplete-current-completions
362 (memq last-command '(pcomplete
363 pcomplete-expand-and-complete
364 pcomplete-reverse)))
365 (progn
366 (delete-backward-char pcomplete-last-completion-length)
367 (if (eq this-command 'pcomplete-reverse)
368 (progn
369 (setq pcomplete-current-completions
370 (cons (car (last pcomplete-current-completions))
371 pcomplete-current-completions))
372 (setcdr (last pcomplete-current-completions 2) nil))
373 (nconc pcomplete-current-completions
374 (list (car pcomplete-current-completions)))
375 (setq pcomplete-current-completions
376 (cdr pcomplete-current-completions)))
377 (pcomplete-insert-entry pcomplete-last-completion-stub
378 (car pcomplete-current-completions)
379 nil pcomplete-last-completion-raw))
380 (setq pcomplete-current-completions nil
381 pcomplete-last-completion-raw nil)
382 (catch 'pcompleted
383 (let* ((pcomplete-stub)
384 pcomplete-seen pcomplete-norm-func
385 pcomplete-args pcomplete-last pcomplete-index
386 (pcomplete-autolist pcomplete-autolist)
387 (pcomplete-suffix-list pcomplete-suffix-list)
388 (completions (pcomplete-completions))
389 (result (pcomplete-do-complete pcomplete-stub completions)))
390 (and result
391 (not (eq (car result) 'listed))
392 (cdr result)
393 (pcomplete-insert-entry pcomplete-stub (cdr result)
394 (memq (car result)
395 '(sole shortest))
396 pcomplete-last-completion-raw))))))
398 ;;;###autoload
399 (defun pcomplete-reverse ()
400 "If cycling completion is in use, cycle backwards."
401 (interactive)
402 (call-interactively 'pcomplete))
404 ;;;###autoload
405 (defun pcomplete-expand-and-complete ()
406 "Expand the textual value of the current argument.
407 This will modify the current buffer."
408 (interactive)
409 (let ((pcomplete-expand-before-complete t))
410 (pcomplete)))
412 ;;;###autoload
413 (defun pcomplete-continue ()
414 "Complete without reference to any cycling completions."
415 (interactive)
416 (setq pcomplete-current-completions nil
417 pcomplete-last-completion-raw nil)
418 (call-interactively 'pcomplete))
420 ;;;###autoload
421 (defun pcomplete-expand ()
422 "Expand the textual value of the current argument.
423 This will modify the current buffer."
424 (interactive)
425 (let ((pcomplete-expand-before-complete t)
426 (pcomplete-expand-only-p t))
427 (pcomplete)
428 (when (and pcomplete-current-completions
429 (> (length pcomplete-current-completions) 0))
430 (delete-backward-char pcomplete-last-completion-length)
431 (while pcomplete-current-completions
432 (unless (pcomplete-insert-entry
433 "" (car pcomplete-current-completions) t
434 pcomplete-last-completion-raw)
435 (insert-and-inherit pcomplete-termination-string))
436 (setq pcomplete-current-completions
437 (cdr pcomplete-current-completions))))))
439 ;;;###autoload
440 (defun pcomplete-help ()
441 "Display any help information relative to the current argument."
442 (interactive)
443 (let ((pcomplete-show-help t))
444 (pcomplete)))
446 ;;;###autoload
447 (defun pcomplete-list ()
448 "Show the list of possible completions for the current argument."
449 (interactive)
450 (when (and pcomplete-cycle-completions
451 pcomplete-current-completions
452 (eq last-command 'pcomplete-argument))
453 (delete-backward-char pcomplete-last-completion-length)
454 (setq pcomplete-current-completions nil
455 pcomplete-last-completion-raw nil))
456 (let ((pcomplete-show-list t))
457 (pcomplete)))
459 ;;; Internal Functions:
461 ;; argument handling
463 ;; for the sake of the bye-compiler, when compiling other files that
464 ;; contain completion functions
465 (defvar pcomplete-args nil)
466 (defvar pcomplete-begins nil)
467 (defvar pcomplete-last nil)
468 (defvar pcomplete-index nil)
469 (defvar pcomplete-stub nil)
470 (defvar pcomplete-seen nil)
471 (defvar pcomplete-norm-func nil)
473 (defun pcomplete-arg (&optional index offset)
474 "Return the textual content of the INDEXth argument.
475 INDEX is based from the current processing position. If INDEX is
476 positive, values returned are closer to the command argument; if
477 negative, they are closer to the last argument. If the INDEX is
478 outside of the argument list, nil is returned. The default value for
479 INDEX is 0, meaning the current argument being examined.
481 The special indices `first' and `last' may be used to access those
482 parts of the list.
484 The OFFSET argument is added to/taken away from the index that will be
485 used. This is really only useful with `first' and `last', for
486 accessing absolute argument positions."
487 (setq index
488 (if (eq index 'first)
490 (if (eq index 'last)
491 pcomplete-last
492 (- pcomplete-index (or index 0)))))
493 (if offset
494 (setq index (+ index offset)))
495 (nth index pcomplete-args))
497 (defun pcomplete-begin (&optional index offset)
498 "Return the beginning position of the INDEXth argument.
499 See the documentation for `pcomplete-arg'."
500 (setq index
501 (if (eq index 'first)
503 (if (eq index 'last)
504 pcomplete-last
505 (- pcomplete-index (or index 0)))))
506 (if offset
507 (setq index (+ index offset)))
508 (nth index pcomplete-begins))
510 (defsubst pcomplete-actual-arg (&optional index offset)
511 "Return the actual text representation of the last argument.
512 This is different from `pcomplete-arg', which returns the textual value
513 that the last argument evaluated to. This function returns what the
514 user actually typed in."
515 (buffer-substring (pcomplete-begin index offset) (point)))
517 (defsubst pcomplete-next-arg ()
518 "Move the various pointers to the next argument."
519 (setq pcomplete-index (1+ pcomplete-index)
520 pcomplete-stub (pcomplete-arg))
521 (if (> pcomplete-index pcomplete-last)
522 (progn
523 (message "No completions")
524 (throw 'pcompleted nil))))
526 (defun pcomplete-command-name ()
527 "Return the command name of the first argument."
528 (file-name-nondirectory (pcomplete-arg 'first)))
530 (defun pcomplete-match (regexp &optional index offset start)
531 "Like `string-match', but on the current completion argument."
532 (let ((arg (pcomplete-arg (or index 1) offset)))
533 (if arg
534 (string-match regexp arg start)
535 (throw 'pcompleted nil))))
537 (defun pcomplete-match-string (which &optional index offset)
538 "Like `match-string', but on the current completion argument."
539 (let ((arg (pcomplete-arg (or index 1) offset)))
540 (if arg
541 (match-string which arg)
542 (throw 'pcompleted nil))))
544 (defalias 'pcomplete-match-beginning 'match-beginning)
545 (defalias 'pcomplete-match-end 'match-end)
547 (defsubst pcomplete--test (pred arg)
548 "Perform a programmable completion predicate match."
549 (and pred
550 (cond ((eq pred t) t)
551 ((functionp pred)
552 (funcall pred arg))
553 ((stringp pred)
554 (string-match (concat "^" pred "$") arg)))
555 pred))
557 (defun pcomplete-test (predicates &optional index offset)
558 "Predicates to test the current programmable argument with."
559 (let ((arg (pcomplete-arg (or index 1) offset)))
560 (unless (null predicates)
561 (if (not (listp predicates))
562 (pcomplete--test predicates arg)
563 (let ((pred predicates)
564 found)
565 (while (and pred (not found))
566 (setq found (pcomplete--test (car pred) arg)
567 pred (cdr pred)))
568 found)))))
570 (defun pcomplete-parse-buffer-arguments ()
571 "Parse whitespace separated arguments in the current region."
572 (let ((begin (point-min))
573 (end (point-max))
574 begins args)
575 (save-excursion
576 (goto-char begin)
577 (while (< (point) end)
578 (skip-chars-forward " \t\n")
579 (setq begins (cons (point) begins))
580 (skip-chars-forward "^ \t\n")
581 (setq args (cons (buffer-substring-no-properties
582 (car begins) (point))
583 args)))
584 (cons (reverse args) (reverse begins)))))
586 ;;;###autoload
587 (defun pcomplete-comint-setup (completef-sym)
588 "Setup a comint buffer to use pcomplete.
589 COMPLETEF-SYM should be the symbol where the
590 dynamic-complete-functions are kept. For comint mode itself,
591 this is `comint-dynamic-complete-functions'."
592 (set (make-local-variable 'pcomplete-parse-arguments-function)
593 'pcomplete-parse-comint-arguments)
594 (make-local-variable completef-sym)
595 (let ((elem (memq 'comint-dynamic-complete-filename
596 (symbol-value completef-sym))))
597 (if elem
598 (setcar elem 'pcomplete)
599 (add-to-list completef-sym 'pcomplete))))
601 ;;;###autoload
602 (defun pcomplete-shell-setup ()
603 "Setup shell-mode to use pcomplete."
604 (pcomplete-comint-setup 'shell-dynamic-complete-functions))
606 (declare-function comint-bol "comint" (&optional arg))
608 (defun pcomplete-parse-comint-arguments ()
609 "Parse whitespace separated arguments in the current region."
610 (let ((begin (save-excursion (comint-bol nil) (point)))
611 (end (point))
612 begins args)
613 (save-excursion
614 (goto-char begin)
615 (while (< (point) end)
616 (skip-chars-forward " \t\n")
617 (setq begins (cons (point) begins))
618 (let ((skip t))
619 (while skip
620 (skip-chars-forward "^ \t\n")
621 (if (eq (char-before) ?\\)
622 (skip-chars-forward " \t\n")
623 (setq skip nil))))
624 (setq args (cons (buffer-substring-no-properties
625 (car begins) (point))
626 args)))
627 (cons (reverse args) (reverse begins)))))
629 (defun pcomplete-parse-arguments (&optional expand-p)
630 "Parse the command line arguments. Most completions need this info."
631 (let ((results (funcall pcomplete-parse-arguments-function)))
632 (when results
633 (setq pcomplete-args (or (car results) (list ""))
634 pcomplete-begins (or (cdr results) (list (point)))
635 pcomplete-last (1- (length pcomplete-args))
636 pcomplete-index 0
637 pcomplete-stub (pcomplete-arg 'last))
638 (let ((begin (pcomplete-begin 'last)))
639 (if (and pcomplete-cycle-completions
640 (listp pcomplete-stub)
641 (not pcomplete-expand-only-p))
642 (let* ((completions pcomplete-stub)
643 (common-stub (car completions))
644 (c completions)
645 (len (length common-stub)))
646 (while (and c (> len 0))
647 (while (and (> len 0)
648 (not (string=
649 (substring common-stub 0 len)
650 (substring (car c) 0
651 (min (length (car c))
652 len)))))
653 (setq len (1- len)))
654 (setq c (cdr c)))
655 (setq pcomplete-stub (substring common-stub 0 len)
656 pcomplete-autolist t)
657 (when (and begin (not pcomplete-show-list))
658 (delete-region begin (point))
659 (pcomplete-insert-entry "" pcomplete-stub))
660 (throw 'pcomplete-completions completions))
661 (when expand-p
662 (if (stringp pcomplete-stub)
663 (when begin
664 (delete-region begin (point))
665 (insert-and-inherit pcomplete-stub))
666 (if (and (listp pcomplete-stub)
667 pcomplete-expand-only-p)
668 ;; this is for the benefit of `pcomplete-expand'
669 (setq pcomplete-last-completion-length (- (point) begin)
670 pcomplete-current-completions pcomplete-stub)
671 (error "Cannot expand argument"))))
672 (if pcomplete-expand-only-p
673 (throw 'pcompleted t)
674 pcomplete-args))))))
676 (defun pcomplete-quote-argument (filename)
677 "Return FILENAME with magic characters quoted.
678 Magic characters are those in `pcomplete-arg-quote-list'."
679 (if (null pcomplete-arg-quote-list)
680 filename
681 (let ((len (length filename))
682 (index 0)
683 (result "")
684 replacement char)
685 (while (< index len)
686 (setq replacement (run-hook-with-args-until-success
687 'pcomplete-quote-arg-hook filename index))
688 (cond
689 (replacement
690 (setq result (concat result replacement)))
691 ((and (setq char (aref filename index))
692 (memq char pcomplete-arg-quote-list))
693 (setq result (concat result "\\" (char-to-string char))))
695 (setq result (concat result (char-to-string char)))))
696 (setq index (1+ index)))
697 result)))
699 ;; file-system completion lists
701 (defsubst pcomplete-dirs-or-entries (&optional regexp predicate)
702 "Return either directories, or qualified entries."
703 (append (let ((pcomplete-stub pcomplete-stub))
704 (pcomplete-entries
705 regexp (or predicate
706 (function
707 (lambda (path)
708 (not (file-directory-p path)))))))
709 (pcomplete-entries nil 'file-directory-p)))
711 (defun pcomplete-entries (&optional regexp predicate)
712 "Complete against a list of directory candidates.
713 If REGEXP is non-nil, it is a regular expression used to refine the
714 match (files not matching the REGEXP will be excluded).
715 If PREDICATE is non-nil, it will also be used to refine the match
716 \(files for which the PREDICATE returns nil will be excluded).
717 If no directory information can be extracted from the completed
718 component, `default-directory' is used as the basis for completion."
719 (let* ((name (substitute-env-vars pcomplete-stub))
720 (completion-ignore-case pcomplete-ignore-case)
721 (default-directory (expand-file-name
722 (or (file-name-directory name)
723 default-directory)))
724 above-cutoff)
725 (setq name (file-name-nondirectory name)
726 pcomplete-stub name)
727 (let ((completions
728 (file-name-all-completions name default-directory)))
729 (if regexp
730 (setq completions
731 (pcomplete-pare-list
732 completions nil
733 (function
734 (lambda (file)
735 (not (string-match regexp file)))))))
736 (if predicate
737 (setq completions
738 (pcomplete-pare-list
739 completions nil
740 (function
741 (lambda (file)
742 (not (funcall predicate file)))))))
743 (if (or pcomplete-file-ignore pcomplete-dir-ignore)
744 (setq completions
745 (pcomplete-pare-list
746 completions nil
747 (function
748 (lambda (file)
749 (if (eq (aref file (1- (length file)))
751 (and pcomplete-dir-ignore
752 (string-match pcomplete-dir-ignore file))
753 (and pcomplete-file-ignore
754 (string-match pcomplete-file-ignore file))))))))
755 (setq above-cutoff (and pcomplete-cycle-cutoff-length
756 (> (length completions)
757 pcomplete-cycle-cutoff-length)))
758 (sort completions
759 (function
760 (lambda (l r)
761 ;; for the purposes of comparison, remove the
762 ;; trailing slash from directory names.
763 ;; Otherwise, "foo.old/" will come before "foo/",
764 ;; since . is earlier in the ASCII alphabet than
765 ;; /
766 (let ((left (if (eq (aref l (1- (length l)))
768 (substring l 0 (1- (length l)))
770 (right (if (eq (aref r (1- (length r)))
772 (substring r 0 (1- (length r)))
773 r)))
774 (if above-cutoff
775 (string-lessp left right)
776 (funcall pcomplete-compare-entry-function
777 left right)))))))))
779 (defsubst pcomplete-all-entries (&optional regexp predicate)
780 "Like `pcomplete-entries', but doesn't ignore any entries."
781 (let (pcomplete-file-ignore
782 pcomplete-dir-ignore)
783 (pcomplete-entries regexp predicate)))
785 (defsubst pcomplete-dirs (&optional regexp)
786 "Complete amongst a list of directories."
787 (pcomplete-entries regexp 'file-directory-p))
789 ;; generation of completion lists
791 (defun pcomplete-find-completion-function (command)
792 "Find the completion function to call for the given COMMAND."
793 (let ((sym (intern-soft
794 (concat "pcomplete/" (symbol-name major-mode) "/" command))))
795 (unless sym
796 (setq sym (intern-soft (concat "pcomplete/" command))))
797 (and sym (fboundp sym) sym)))
799 (defun pcomplete-completions ()
800 "Return a list of completions for the current argument position."
801 (catch 'pcomplete-completions
802 (when (pcomplete-parse-arguments pcomplete-expand-before-complete)
803 (if (= pcomplete-index pcomplete-last)
804 (funcall pcomplete-command-completion-function)
805 (let ((sym (or (pcomplete-find-completion-function
806 (funcall pcomplete-command-name-function))
807 pcomplete-default-completion-function)))
808 (ignore
809 (pcomplete-next-arg)
810 (funcall sym)))))))
812 (defun pcomplete-opt (options &optional prefix no-ganging args-follow)
813 "Complete a set of OPTIONS, each beginning with PREFIX (?- by default).
814 PREFIX may be t, in which case no PREFIX character is necessary.
815 If NO-GANGING is non-nil, each option is separate (-xy is not allowed).
816 If ARGS-FOLLOW is non-nil, then options which take arguments may have
817 the argument appear after a ganged set of options. This is how tar
818 behaves, for example."
819 (if (and (= pcomplete-index pcomplete-last)
820 (string= (pcomplete-arg) "-"))
821 (let ((len (length options))
822 (index 0)
823 char choices)
824 (while (< index len)
825 (setq char (aref options index))
826 (if (eq char ?\()
827 (let ((result (read-from-string options index)))
828 (setq index (cdr result)))
829 (unless (memq char '(?/ ?* ?? ?.))
830 (setq choices (cons (char-to-string char) choices)))
831 (setq index (1+ index))))
832 (throw 'pcomplete-completions
833 (mapcar
834 (function
835 (lambda (opt)
836 (concat "-" opt)))
837 (pcomplete-uniqify-list choices))))
838 (let ((arg (pcomplete-arg)))
839 (when (and (> (length arg) 1)
840 (stringp arg)
841 (eq (aref arg 0) (or prefix ?-)))
842 (pcomplete-next-arg)
843 (let ((char (aref arg 1))
844 (len (length options))
845 (index 0)
846 opt-char arg-char result)
847 (while (< (1+ index) len)
848 (setq opt-char (aref options index)
849 arg-char (aref options (1+ index)))
850 (if (eq arg-char ?\()
851 (setq result
852 (read-from-string options (1+ index))
853 index (cdr result)
854 result (car result))
855 (setq result nil))
856 (when (and (eq char opt-char)
857 (memq arg-char '(?\( ?/ ?* ?? ?.)))
858 (if (< pcomplete-index pcomplete-last)
859 (pcomplete-next-arg)
860 (throw 'pcomplete-completions
861 (cond ((eq arg-char ?/) (pcomplete-dirs))
862 ((eq arg-char ?*) (pcomplete-executables))
863 ((eq arg-char ??) nil)
864 ((eq arg-char ?.) (pcomplete-entries))
865 ((eq arg-char ?\() (eval result))))))
866 (setq index (1+ index))))))))
868 (defun pcomplete--here (&optional form stub paring form-only)
869 "Complete against the current argument, if at the end.
870 See the documentation for `pcomplete-here'."
871 (if (< pcomplete-index pcomplete-last)
872 (progn
873 (if (eq paring 0)
874 (setq pcomplete-seen nil)
875 (unless (eq paring t)
876 (let ((arg (pcomplete-arg)))
877 (unless (not (stringp arg))
878 (setq pcomplete-seen
879 (cons (if paring
880 (funcall paring arg)
881 (file-truename arg))
882 pcomplete-seen))))))
883 (pcomplete-next-arg)
885 (when pcomplete-show-help
886 (pcomplete--help)
887 (throw 'pcompleted t))
888 (if stub
889 (setq pcomplete-stub stub))
890 (if (or (eq paring t) (eq paring 0))
891 (setq pcomplete-seen nil)
892 (setq pcomplete-norm-func (or paring 'file-truename)))
893 (unless form-only
894 (run-hooks 'pcomplete-try-first-hook))
895 (throw 'pcomplete-completions (eval form))))
897 (defmacro pcomplete-here (&optional form stub paring form-only)
898 "Complete against the current argument, if at the end.
899 If completion is to be done here, evaluate FORM to generate the list
900 of strings which will be used for completion purposes. If STUB is a
901 string, use it as the completion stub instead of the default (which is
902 the entire text of the current argument).
904 For an example of when you might want to use STUB: if the current
905 argument text is 'long-path-name/', you don't want the completions
906 list display to be cluttered by 'long-path-name/' appearing at the
907 beginning of every alternative. Not only does this make things less
908 intelligle, but it is also inefficient. Yet, if the completion list
909 does not begin with this string for every entry, the current argument
910 won't complete correctly.
912 The solution is to specify a relative stub. It allows you to
913 substitute a different argument from the current argument, almost
914 always for the sake of efficiency.
916 If PARING is nil, this argument will be pared against previous
917 arguments using the function `file-truename' to normalize them.
918 PARING may be a function, in which case that function is used for
919 normalization. If PARING is t, the argument dealt with by this
920 call will not participate in argument paring. If it is the
921 integer 0, all previous arguments that have been seen will be
922 cleared.
924 If FORM-ONLY is non-nil, only the result of FORM will be used to
925 generate the completions list. This means that the hook
926 `pcomplete-try-first-hook' will not be run."
927 `(pcomplete--here (quote ,form) ,stub ,paring ,form-only))
929 (defmacro pcomplete-here* (&optional form stub form-only)
930 "An alternate form which does not participate in argument paring."
931 `(pcomplete-here ,form ,stub t ,form-only))
933 ;; display support
935 (defun pcomplete-restore-windows ()
936 "If the only window change was due to Completions, restore things."
937 (if pcomplete-last-window-config
938 (let* ((cbuf (get-buffer "*Completions*"))
939 (cwin (and cbuf (get-buffer-window cbuf))))
940 (when (window-live-p cwin)
941 (bury-buffer cbuf)
942 (set-window-configuration pcomplete-last-window-config))))
943 (setq pcomplete-last-window-config nil
944 pcomplete-window-restore-timer nil))
946 ;; Abstractions so that the code below will work for both Emacs 20 and
947 ;; XEmacs 21
949 (defalias 'pcomplete-event-matches-key-specifier-p
950 (if (featurep 'xemacs)
951 'event-matches-key-specifier-p
952 'eq))
954 (defun pcomplete-read-event (&optional prompt)
955 (if (fboundp 'read-event)
956 (read-event prompt)
957 (aref (read-key-sequence prompt) 0)))
959 (defun pcomplete-show-completions (completions)
960 "List in help buffer sorted COMPLETIONS.
961 Typing SPC flushes the help buffer."
962 (let* ((curbuf (current-buffer)))
963 (when pcomplete-window-restore-timer
964 (cancel-timer pcomplete-window-restore-timer)
965 (setq pcomplete-window-restore-timer nil))
966 (unless pcomplete-last-window-config
967 (setq pcomplete-last-window-config (current-window-configuration)))
968 (with-output-to-temp-buffer "*Completions*"
969 (display-completion-list completions))
970 (message "Hit space to flush")
971 (let (event)
972 (prog1
973 (catch 'done
974 (while (with-current-buffer (get-buffer "*Completions*")
975 (setq event (pcomplete-read-event)))
976 (cond
977 ((pcomplete-event-matches-key-specifier-p event ?\s)
978 (set-window-configuration pcomplete-last-window-config)
979 (setq pcomplete-last-window-config nil)
980 (throw 'done nil))
981 ((or (pcomplete-event-matches-key-specifier-p event 'tab)
982 ;; Needed on a terminal
983 (pcomplete-event-matches-key-specifier-p event 9))
984 (let ((win (or (get-buffer-window "*Completions*" 0)
985 (display-buffer "*Completions*"
986 'not-this-window))))
987 (with-selected-window win
988 (if (pos-visible-in-window-p (point-max))
989 (goto-char (point-min))
990 (scroll-up))))
991 (message ""))
993 (setq unread-command-events (list event))
994 (throw 'done nil)))))
995 (if (and pcomplete-last-window-config
996 pcomplete-restore-window-delay)
997 (setq pcomplete-window-restore-timer
998 (run-with-timer pcomplete-restore-window-delay nil
999 'pcomplete-restore-windows)))))))
1001 ;; insert completion at point
1003 (defun pcomplete-insert-entry (stub entry &optional addsuffix raw-p)
1004 "Insert a completion entry at point.
1005 Returns non-nil if a space was appended at the end."
1006 (let ((here (point)))
1007 (if (not pcomplete-ignore-case)
1008 (insert-and-inherit (if raw-p
1009 (substring entry (length stub))
1010 (pcomplete-quote-argument
1011 (substring entry (length stub)))))
1012 ;; the stub is not quoted at this time, so to determine the
1013 ;; length of what should be in the buffer, we must quote it
1014 (delete-backward-char (length (pcomplete-quote-argument stub)))
1015 ;; if there is already a backslash present to handle the first
1016 ;; character, don't bother quoting it
1017 (when (eq (char-before) ?\\)
1018 (insert-and-inherit (substring entry 0 1))
1019 (setq entry (substring entry 1)))
1020 (insert-and-inherit (if raw-p
1021 entry
1022 (pcomplete-quote-argument entry))))
1023 (let (space-added)
1024 (when (and (not (memq (char-before) pcomplete-suffix-list))
1025 addsuffix)
1026 (insert-and-inherit pcomplete-termination-string)
1027 (setq space-added t))
1028 (setq pcomplete-last-completion-length (- (point) here)
1029 pcomplete-last-completion-stub stub)
1030 space-added)))
1032 ;; selection of completions
1034 (defun pcomplete-do-complete (stub completions)
1035 "Dynamically complete at point using STUB and COMPLETIONS.
1036 This is basically just a wrapper for `pcomplete-stub' which does some
1037 extra checking, and munging of the COMPLETIONS list."
1038 (unless (stringp stub)
1039 (message "Cannot complete argument")
1040 (throw 'pcompleted nil))
1041 (if (null completions)
1042 (ignore
1043 (if (and stub (> (length stub) 0))
1044 (message "No completions of %s" stub)
1045 (message "No completions")))
1046 ;; pare it down, if applicable
1047 (if (and pcomplete-use-paring pcomplete-seen)
1048 (let* ((arg (pcomplete-arg))
1049 (prefix
1050 (file-name-as-directory
1051 (funcall pcomplete-norm-func
1052 (substring arg 0 (- (length arg)
1053 (length pcomplete-stub)))))))
1054 (setq pcomplete-seen
1055 (mapcar 'directory-file-name pcomplete-seen))
1056 (let ((p pcomplete-seen))
1057 (while p
1058 (add-to-list 'pcomplete-seen
1059 (funcall pcomplete-norm-func (car p)))
1060 (setq p (cdr p))))
1061 (setq completions
1062 (mapcar
1063 (function
1064 (lambda (elem)
1065 (file-relative-name elem prefix)))
1066 (pcomplete-pare-list
1067 (mapcar
1068 (function
1069 (lambda (elem)
1070 (expand-file-name elem prefix)))
1071 completions)
1072 pcomplete-seen
1073 (function
1074 (lambda (elem)
1075 (member (directory-file-name
1076 (funcall pcomplete-norm-func elem))
1077 pcomplete-seen))))))))
1078 ;; OK, we've got a list of completions.
1079 (if pcomplete-show-list
1080 (pcomplete-show-completions completions)
1081 (pcomplete-stub stub completions))))
1083 (defun pcomplete-stub (stub candidates &optional cycle-p)
1084 "Dynamically complete STUB from CANDIDATES list.
1085 This function inserts completion characters at point by completing
1086 STUB from the strings in CANDIDATES. A completions listing may be
1087 shown in a help buffer if completion is ambiguous.
1089 Returns nil if no completion was inserted.
1090 Returns `sole' if completed with the only completion match.
1091 Returns `shortest' if completed with the shortest of the matches.
1092 Returns `partial' if completed as far as possible with the matches.
1093 Returns `listed' if a completion listing was shown.
1095 See also `pcomplete-filename'."
1096 (let* ((completion-ignore-case pcomplete-ignore-case)
1097 (candidates (mapcar 'list candidates))
1098 (completions (all-completions stub candidates)))
1099 (let (result entry)
1100 (cond
1101 ((null completions)
1102 (if (and stub (> (length stub) 0))
1103 (message "No completions of %s" stub)
1104 (message "No completions")))
1105 ((= 1 (length completions))
1106 (setq entry (car completions))
1107 (if (string-equal entry stub)
1108 (message "Sole completion"))
1109 (setq result 'sole))
1110 ((and pcomplete-cycle-completions
1111 (or cycle-p
1112 (not pcomplete-cycle-cutoff-length)
1113 (<= (length completions)
1114 pcomplete-cycle-cutoff-length)))
1115 (setq entry (car completions)
1116 pcomplete-current-completions completions))
1117 (t ; There's no unique completion; use longest substring
1118 (setq entry (try-completion stub candidates))
1119 (cond ((and pcomplete-recexact
1120 (string-equal stub entry)
1121 (member entry completions))
1122 ;; It's not unique, but user wants shortest match.
1123 (message "Completed shortest")
1124 (setq result 'shortest))
1125 ((or pcomplete-autolist
1126 (string-equal stub entry))
1127 ;; It's not unique, list possible completions.
1128 (pcomplete-show-completions completions)
1129 (setq result 'listed))
1131 (message "Partially completed")
1132 (setq result 'partial)))))
1133 (cons result entry))))
1135 ;; context sensitive help
1137 (defun pcomplete--help ()
1138 "Produce context-sensitive help for the current argument.
1139 If specific documentation can't be given, be generic."
1140 (if (and pcomplete-help
1141 (or (and (stringp pcomplete-help)
1142 (fboundp 'Info-goto-node))
1143 (listp pcomplete-help)))
1144 (if (listp pcomplete-help)
1145 (message "%s" (eval pcomplete-help))
1146 (save-window-excursion (info))
1147 (switch-to-buffer-other-window "*info*")
1148 (funcall (symbol-function 'Info-goto-node) pcomplete-help))
1149 (if pcomplete-man-function
1150 (let ((cmd (funcall pcomplete-command-name-function)))
1151 (if (and cmd (> (length cmd) 0))
1152 (funcall pcomplete-man-function cmd)))
1153 (message "No context-sensitive help available"))))
1155 ;; general utilities
1157 (defun pcomplete-pare-list (l r &optional pred)
1158 "Destructively remove from list L all elements matching any in list R.
1159 Test is done using `equal'.
1160 If PRED is non-nil, it is a function used for further removal.
1161 Returns the resultant list."
1162 (while (and l (or (and r (member (car l) r))
1163 (and pred
1164 (funcall pred (car l)))))
1165 (setq l (cdr l)))
1166 (let ((m l))
1167 (while m
1168 (while (and (cdr m)
1169 (or (and r (member (cadr m) r))
1170 (and pred
1171 (funcall pred (cadr m)))))
1172 (setcdr m (cddr m)))
1173 (setq m (cdr m))))
1176 (defun pcomplete-uniqify-list (l)
1177 "Sort and remove multiples in L."
1178 (setq l (sort l 'string-lessp))
1179 (let ((m l))
1180 (while m
1181 (while (and (cdr m)
1182 (string= (car m)
1183 (cadr m)))
1184 (setcdr m (cddr m)))
1185 (setq m (cdr m))))
1188 (defun pcomplete-process-result (cmd &rest args)
1189 "Call CMD using `call-process' and return the simplest result."
1190 (with-temp-buffer
1191 (apply 'call-process cmd nil t nil args)
1192 (skip-chars-backward "\n")
1193 (buffer-substring (point-min) (point))))
1195 ;; create a set of aliases which allow completion functions to be not
1196 ;; quite so verbose
1198 ;; jww (1999-10-20): are these a good idea?
1199 ; (defalias 'pc-here 'pcomplete-here)
1200 ; (defalias 'pc-test 'pcomplete-test)
1201 ; (defalias 'pc-opt 'pcomplete-opt)
1202 ; (defalias 'pc-match 'pcomplete-match)
1203 ; (defalias 'pc-match-string 'pcomplete-match-string)
1204 ; (defalias 'pc-match-beginning 'pcomplete-match-beginning)
1205 ; (defalias 'pc-match-end 'pcomplete-match-end)
1207 ;;; arch-tag: ae32ef2d-dbed-4244-8b0f-cf5a2a3b07a4
1208 ;;; pcomplete.el ends here