* lisp/subr.el (event-start, event-end): Doc fix (Bug#7826).
[emacs.git] / lisp / pcomplete.el
blobb3367dc4c742a1e9883e45a973d915ebaa7febfa
1 ;;; pcomplete.el --- programmable completion
3 ;; Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004
4 ;; 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 of the License, or
14 ;; (at your option) 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. If not, see <http://www.gnu.org/licenses/>.
24 ;;; Commentary:
26 ;; This module provides a programmable completion facility using
27 ;; "completion functions". Each completion function is responsible
28 ;; for producing a list of possible completions relevant to the current
29 ;; argument position.
31 ;; To use pcomplete with shell-mode, for example, you will need the
32 ;; following in your .emacs file:
34 ;; (add-hook 'shell-mode-hook 'pcomplete-shell-setup)
36 ;; Most of the code below simply provides support mechanisms for
37 ;; writing completion functions. Completion functions themselves are
38 ;; very easy to write. They have few requirements beyond those of
39 ;; regular Lisp functions.
41 ;; Consider the following example, which will complete against
42 ;; filenames for the first two arguments, and directories for all
43 ;; remaining arguments:
45 ;; (defun pcomplete/my-command ()
46 ;; (pcomplete-here (pcomplete-entries))
47 ;; (pcomplete-here (pcomplete-entries))
48 ;; (while (pcomplete-here (pcomplete-dirs))))
50 ;; Here are the requirements for completion functions:
52 ;; @ They must be called "pcomplete/MAJOR-MODE/NAME", or
53 ;; "pcomplete/NAME". This is how they are looked up, using the NAME
54 ;; specified in the command argument (the argument in first
55 ;; position).
57 ;; @ They must be callable with no arguments.
59 ;; @ Their return value is ignored. If they actually return normally,
60 ;; it means no completions were available.
62 ;; @ In order to provide completions, they must throw the tag
63 ;; `pcomplete-completions'. The value must be a completion table
64 ;; (i.e. a table that can be passed to try-completion and friends)
65 ;; for the final argument.
67 ;; @ To simplify completion function logic, the tag `pcompleted' may
68 ;; be thrown with a value of nil in order to abort the function. It
69 ;; means that there were no completions available.
71 ;; When a completion function is called, the variable `pcomplete-args'
72 ;; is in scope, and contains all of the arguments specified on the
73 ;; command line. The variable `pcomplete-last' is the index of the
74 ;; last argument in that list.
76 ;; The variable `pcomplete-index' is used by the completion code to
77 ;; know which argument the completion function is currently examining.
78 ;; It always begins at 1, meaning the first argument after the command
79 ;; name.
81 ;; To facilitate writing completion logic, a special macro,
82 ;; `pcomplete-here', has been provided which does several things:
84 ;; 1. It will throw `pcompleted' (with a value of nil) whenever
85 ;; `pcomplete-index' exceeds `pcomplete-last'.
87 ;; 2. It will increment `pcomplete-index' if the final argument has
88 ;; not been reached yet.
90 ;; 3. It will evaluate the form passed to it, and throw the result
91 ;; using the `pcomplete-completions' tag, if it is called when
92 ;; `pcomplete-index' is pointing to the final argument.
94 ;; Sometimes a completion function will want to vary the possible
95 ;; completions for an argument based on the previous one. To
96 ;; facilitate tests like this, the function `pcomplete-test' and
97 ;; `pcomplete-match' are provided. Called with one argument, they
98 ;; test the value of the previous command argument. Otherwise, a
99 ;; relative index may be given as an optional second argument, where 0
100 ;; refers to the current argument, 1 the previous, 2 the one before
101 ;; that, etc. The symbols `first' and `last' specify absolute
102 ;; offsets.
104 ;; Here is an example which will only complete against directories for
105 ;; the second argument if the first argument is also a directory:
107 ;; (defun pcomplete/example ()
108 ;; (pcomplete-here (pcomplete-entries))
109 ;; (if (pcomplete-test 'file-directory-p)
110 ;; (pcomplete-here (pcomplete-dirs))
111 ;; (pcomplete-here (pcomplete-entries))))
113 ;; For generating completion lists based on directory contents, see
114 ;; the functions `pcomplete-entries', `pcomplete-dirs',
115 ;; `pcomplete-executables' and `pcomplete-all-entries'.
117 ;; Consult the documentation for `pcomplete-here' for information
118 ;; about its other arguments.
120 ;;; Code:
122 (eval-when-compile (require 'cl))
124 (defgroup pcomplete nil
125 "Programmable completion."
126 :version "21.1"
127 :group 'processes)
129 ;;; User Variables:
131 (defcustom pcomplete-file-ignore nil
132 "A regexp of filenames to be disregarded during file completion."
133 :type '(choice regexp (const :tag "None" nil))
134 :group 'pcomplete)
136 (defcustom pcomplete-dir-ignore nil
137 "A regexp of names to be disregarded during directory completion."
138 :type '(choice regexp (const :tag "None" nil))
139 :group 'pcomplete)
141 (defcustom pcomplete-ignore-case (memq system-type '(ms-dos windows-nt cygwin))
142 ;; FIXME: the doc mentions file-name completion, but the code
143 ;; seems to apply it to all completions.
144 "If non-nil, ignore case when doing filename completion."
145 :type 'boolean
146 :group 'pcomplete)
148 (defcustom pcomplete-autolist nil
149 "If non-nil, automatically list possibilities on partial completion.
150 This mirrors the optional behavior of tcsh."
151 :type 'boolean
152 :group 'pcomplete)
154 (defcustom pcomplete-suffix-list (list ?/ ?:)
155 "A list of characters which constitute a proper suffix."
156 :type '(repeat character)
157 :group 'pcomplete)
159 (defcustom pcomplete-recexact nil
160 "If non-nil, use shortest completion if characters cannot be added.
161 This mirrors the optional behavior of tcsh.
163 A non-nil value is useful if `pcomplete-autolist' is non-nil too."
164 :type 'boolean
165 :group 'pcomplete)
167 (defcustom pcomplete-arg-quote-list nil
168 "List of characters to quote when completing an argument."
169 :type '(choice (repeat character)
170 (const :tag "Don't quote" nil))
171 :group 'pcomplete)
173 (defcustom pcomplete-quote-arg-hook nil
174 "A hook which is run to quote a character within a filename.
175 Each function is passed both the filename to be quoted, and the index
176 to be considered. If the function wishes to provide an alternate
177 quoted form, it need only return the replacement string. If no
178 function provides a replacement, quoting shall proceed as normal,
179 using a backslash to quote any character which is a member of
180 `pcomplete-arg-quote-list'."
181 :type 'hook
182 :group 'pcomplete)
184 (defcustom pcomplete-man-function 'man
185 "A function to that will be called to display a manual page.
186 It will be passed the name of the command to document."
187 :type 'function
188 :group 'pcomplete)
190 (defcustom pcomplete-compare-entry-function 'string-lessp
191 "This function is used to order file entries for completion.
192 The behavior of most all shells is to sort alphabetically."
193 :type '(radio (function-item string-lessp)
194 (function-item file-newer-than-file-p)
195 (function :tag "Other"))
196 :group 'pcomplete)
198 (defcustom pcomplete-help nil
199 "A string or function (or nil) used for context-sensitive help.
200 If a string, it should name an Info node that will be jumped to.
201 If non-nil, it must a sexp that will be evaluated, and whose
202 result will be shown in the minibuffer.
203 If nil, the function `pcomplete-man-function' will be called with the
204 current command argument."
205 :type '(choice string sexp (const :tag "Use man page" nil))
206 :group 'pcomplete)
208 (defcustom pcomplete-expand-before-complete nil
209 "If non-nil, expand the current argument before completing it.
210 This means that typing something such as '$HOME/bi' followed by
211 \\[pcomplete-argument] will cause the variable reference to be
212 resolved first, and the resultant value that will be completed against
213 to be inserted in the buffer. Note that exactly what gets expanded
214 and how is entirely up to the behavior of the
215 `pcomplete-parse-arguments-function'."
216 :type 'boolean
217 :group 'pcomplete)
219 (defcustom pcomplete-parse-arguments-function
220 'pcomplete-parse-buffer-arguments
221 "A function to call to parse the current line's arguments.
222 It should be called with no parameters, and with point at the position
223 of the argument that is to be completed.
225 It must either return nil, or a cons cell of the form:
227 ((ARG...) (BEG-POS...))
229 The two lists must be identical in length. The first gives the final
230 value of each command line argument (which need not match the textual
231 representation of that argument), and BEG-POS gives the beginning
232 position of each argument, as it is seen by the user. The establishes
233 a relationship between the fully resolved value of the argument, and
234 the textual representation of the argument."
235 :type 'function
236 :group 'pcomplete)
238 (defcustom pcomplete-cycle-completions t
239 "If non-nil, hitting the TAB key cycles through the completion list.
240 Typical Emacs behavior is to complete as much as possible, then pause
241 waiting for further input. Then if TAB is hit again, show a list of
242 possible completions. When `pcomplete-cycle-completions' is non-nil,
243 it acts more like zsh or 4nt, showing the first maximal match first,
244 followed by any further matches on each subsequent pressing of the TAB
245 key. \\[pcomplete-list] is the key to press if the user wants to see
246 the list of possible completions."
247 :type 'boolean
248 :group 'pcomplete)
250 (defcustom pcomplete-cycle-cutoff-length 5
251 "If the number of completions is greater than this, don't cycle.
252 This variable is a compromise between the traditional Emacs style of
253 completion, and the \"cycling\" style. Basically, if there are more
254 than this number of completions possible, don't automatically pick the
255 first one and then expect the user to press TAB to cycle through them.
256 Typically, when there are a large number of completion possibilities,
257 the user wants to see them in a list buffer so that they can know what
258 options are available. But if the list is small, it means the user
259 has already entered enough input to disambiguate most of the
260 possibilities, and therefore they are probably most interested in
261 cycling through the candidates. Set this value to nil if you want
262 cycling to always be enabled."
263 :type '(choice integer (const :tag "Always cycle" nil))
264 :group 'pcomplete)
266 (defcustom pcomplete-restore-window-delay 1
267 "The number of seconds to wait before restoring completion windows.
268 Once the completion window has been displayed, if the user then goes
269 on to type something else, that completion window will be removed from
270 the display (actually, the original window configuration before it was
271 displayed will be restored), after this many seconds of idle time. If
272 set to nil, completion windows will be left on second until the user
273 removes them manually. If set to 0, they will disappear immediately
274 after the user enters a key other than TAB."
275 :type '(choice integer (const :tag "Never restore" nil))
276 :group 'pcomplete)
278 (defcustom pcomplete-try-first-hook nil
279 "A list of functions which are called before completing an argument.
280 This can be used, for example, for completing things which might apply
281 to all arguments, such as variable names after a $."
282 :type 'hook
283 :group 'pcomplete)
285 (defsubst pcomplete-executables (&optional regexp)
286 "Complete amongst a list of directories and executables."
287 (pcomplete-entries regexp 'file-executable-p))
289 (defcustom pcomplete-command-completion-function
290 (function
291 (lambda ()
292 (pcomplete-here (pcomplete-executables))))
293 "Function called for completing the initial command argument."
294 :type 'function
295 :group 'pcomplete)
297 (defcustom pcomplete-command-name-function 'pcomplete-command-name
298 "Function called for determining the current command name."
299 :type 'function
300 :group 'pcomplete)
302 (defcustom pcomplete-default-completion-function
303 (function
304 (lambda ()
305 (while (pcomplete-here (pcomplete-entries)))))
306 "Function called when no completion rule can be found.
307 This function is used to generate completions for every argument."
308 :type 'function
309 :group 'pcomplete)
311 (defcustom pcomplete-use-paring t
312 "If t, pare alternatives that have already been used.
313 If nil, you will always see the completion set of possible options, no
314 matter which of those options have already been used in previous
315 command arguments."
316 :type 'boolean
317 :group 'pcomplete)
319 (defcustom pcomplete-termination-string " "
320 "A string that is inserted after any completion or expansion.
321 This is usually a space character, useful when completing lists of
322 words separated by spaces. However, if your list uses a different
323 separator character, or if the completion occurs in a word that is
324 already terminated by a character, this variable should be locally
325 modified to be an empty string, or the desired separation string."
326 :type 'string
327 :group 'pcomplete)
329 ;;; Internal Variables:
331 ;; for cycling completion support
332 (defvar pcomplete-current-completions nil)
333 (defvar pcomplete-last-completion-length)
334 (defvar pcomplete-last-completion-stub)
335 (defvar pcomplete-last-completion-raw)
336 (defvar pcomplete-last-window-config nil)
337 (defvar pcomplete-window-restore-timer nil)
339 (make-variable-buffer-local 'pcomplete-current-completions)
340 (make-variable-buffer-local 'pcomplete-last-completion-length)
341 (make-variable-buffer-local 'pcomplete-last-completion-stub)
342 (make-variable-buffer-local 'pcomplete-last-completion-raw)
343 (make-variable-buffer-local 'pcomplete-last-window-config)
344 (make-variable-buffer-local 'pcomplete-window-restore-timer)
346 ;; used for altering pcomplete's behavior. These global variables
347 ;; should always be nil.
348 (defvar pcomplete-show-help nil)
349 (defvar pcomplete-show-list nil)
350 (defvar pcomplete-expand-only-p nil)
352 ;;; User Functions:
354 ;;; Alternative front-end using the standard completion facilities.
356 ;; The way pcomplete-parse-arguments, pcomplete-stub, and
357 ;; pcomplete-quote-argument work only works because of some deep
358 ;; hypothesis about the way the completion work. Basically, it makes
359 ;; it pretty much impossible to have completion other than
360 ;; prefix-completion.
362 ;; pcomplete--common-quoted-suffix and pcomplete--table-subvert try to
363 ;; work around this difficulty with heuristics, but it's
364 ;; really a hack.
366 (defvar pcomplete-unquote-argument-function nil)
368 (defun pcomplete-unquote-argument (s)
369 (cond
370 (pcomplete-unquote-argument-function
371 (funcall pcomplete-unquote-argument-function s))
372 ((null pcomplete-arg-quote-list) s)
374 (replace-regexp-in-string "\\\\\\(.\\)" "\\1" s t))))
376 (defun pcomplete--common-suffix (s1 s2)
377 (assert (not (or (string-match "\n" s1) (string-match "\n" s2))))
378 ;; Since S2 is expected to be the "unquoted/expanded" version of S1,
379 ;; there shouldn't be any case difference, even if the completion is
380 ;; case-insensitive.
381 (let ((case-fold-search nil)) ;; pcomplete-ignore-case
382 (string-match ".*?\\(.*\\)\n.*\\1\\'" (concat s1 "\n" s2))
383 (- (match-end 1) (match-beginning 1))))
385 (defun pcomplete--common-quoted-suffix (s1 s2)
386 "Find the common suffix between S1 and S2 where S1 is the expanded S2.
387 S1 is expected to be the unquoted and expanded version of S1.
388 Returns (PS1 . PS2), i.e. the shortest prefixes of S1 and S2, such that
389 S1 = (concat PS1 SS1) and S2 = (concat PS2 SS2) and
390 SS1 = (unquote SS2)."
391 (let* ((cs (pcomplete--common-suffix s1 s2))
392 (ss1 (substring s1 (- (length s1) cs)))
393 (qss1 (pcomplete-quote-argument ss1))
395 (if (and (not (equal ss1 qss1))
396 (setq qc (pcomplete-quote-argument (substring ss1 0 1)))
397 (eq t (compare-strings s2 (- (length s2) cs (length qc) -1)
398 (- (length s2) cs -1)
399 qc nil nil)))
400 ;; The difference found is just that one char is quoted in S2
401 ;; but not in S1, keep looking before this difference.
402 (pcomplete--common-quoted-suffix
403 (substring s1 0 (- (length s1) cs))
404 (substring s2 0 (- (length s2) cs (length qc) -1)))
405 (cons (substring s1 0 (- (length s1) cs))
406 (substring s2 0 (- (length s2) cs))))))
408 (defun pcomplete--table-subvert (table s1 s2 string pred action)
409 "Completion table that replaces the prefix S1 with S2 in STRING.
410 When TABLE, S1 and S2 are provided by `apply-partially', the result
411 is a completion table which completes strings of the form (concat S1 S)
412 in the same way as TABLE completes strings of the form (concat S2 S)."
413 (let* ((str (if (eq t (compare-strings string 0 (length s1) s1 nil nil
414 completion-ignore-case))
415 (concat s2 (pcomplete-unquote-argument
416 (substring string (length s1))))))
417 (res (if str (complete-with-action action table str pred))))
418 (when res
419 (cond
420 ((and (eq (car-safe action) 'boundaries))
421 (let ((beg (or (and (eq (car-safe res) 'boundaries) (cadr res)) 0)))
422 (list* 'boundaries
423 (max (length s1)
424 ;; FIXME: Adjust because of quoting/unquoting.
425 (+ beg (- (length s1) (length s2))))
426 (and (eq (car-safe res) 'boundaries) (cddr res)))))
427 ((stringp res)
428 (if (eq t (compare-strings res 0 (length s2) s2 nil nil
429 completion-ignore-case))
430 (concat s1 (pcomplete-quote-argument
431 (substring res (length s2))))))
432 ((eq action t)
433 (let ((bounds (completion-boundaries str table pred "")))
434 (if (>= (car bounds) (length s2))
436 (let ((re (concat "\\`"
437 (regexp-quote (substring s2 (car bounds))))))
438 (delq nil
439 (mapcar (lambda (c)
440 (if (string-match re c)
441 (substring c (match-end 0))))
442 res))))))))))
444 ;; I don't think such commands are usable before first setting up buffer-local
445 ;; variables to parse args, so there's no point autoloading it.
446 ;; ;;;###autoload
447 (defun pcomplete-std-complete ()
448 "Provide standard completion using pcomplete's completion tables.
449 Same as `pcomplete' but using the standard completion UI."
450 (interactive)
451 ;; FIXME: it only completes the text before point, whereas the
452 ;; standard UI may also consider text after point.
453 (catch 'pcompleted
454 (let* ((pcomplete-stub)
455 pcomplete-seen pcomplete-norm-func
456 pcomplete-args pcomplete-last pcomplete-index
457 (pcomplete-autolist pcomplete-autolist)
458 (pcomplete-suffix-list pcomplete-suffix-list)
459 ;; Apparently the vars above are global vars modified by
460 ;; side-effects, whereas pcomplete-completions is the core
461 ;; function that finds the chunk of text to complete
462 ;; (returned indirectly in pcomplete-stub) and the set of
463 ;; possible completions.
464 (completions (pcomplete-completions))
465 ;; Usually there's some close connection between pcomplete-stub
466 ;; and the text before point. But depending on what
467 ;; pcomplete-parse-arguments-function does, that connection
468 ;; might not be that close. E.g. in eshell,
469 ;; pcomplete-parse-arguments-function expands envvars.
471 ;; Since we use minibuffer-complete, which doesn't know
472 ;; pcomplete-stub and works from the buffer's text instead,
473 ;; we need to trick minibuffer-complete, into using
474 ;; pcomplete-stub without its knowledge. To that end, we
475 ;; use pcomplete--table-subvert to construct a completion
476 ;; table which expects strings using a prefix from the
477 ;; buffer's text but internally uses the corresponding
478 ;; prefix from pcomplete-stub.
479 (beg (max (- (point) (length pcomplete-stub))
480 (pcomplete-begin)))
481 (buftext (buffer-substring beg (point)))
482 (table
483 (cond
484 ((null completions) nil)
485 ((not (equal pcomplete-stub buftext))
486 ;; This isn't always strictly right (e.g. if
487 ;; FOO="toto/$FOO", then completion of /$FOO/bar may
488 ;; result in something incorrect), but given the lack of
489 ;; any other info, it's about as good as it gets, and in
490 ;; practice it should work just fine (fingers crossed).
491 (let ((prefixes (pcomplete--common-quoted-suffix
492 pcomplete-stub buftext)))
493 (apply-partially
494 'pcomplete--table-subvert
495 completions
496 (cdr prefixes) (car prefixes))))
498 (lexical-let ((completions completions))
499 (lambda (string pred action)
500 (let ((res (complete-with-action
501 action completions string pred)))
502 (if (stringp res)
503 (pcomplete-quote-argument res)
504 res)))))))
505 (pred
506 ;; pare it down, if applicable
507 (when (and table pcomplete-use-paring pcomplete-seen)
508 (setq pcomplete-seen
509 (mapcar (lambda (f)
510 (funcall pcomplete-norm-func
511 (directory-file-name f)))
512 pcomplete-seen))
513 (lambda (f)
514 (not (member
515 (funcall pcomplete-norm-func
516 (directory-file-name f))
517 pcomplete-seen))))))
519 (completion-in-region
520 beg (point)
521 ;; Add a space at the end of completion. Use a terminator-regexp
522 ;; that never matches since the terminator cannot appear
523 ;; within the completion field anyway.
524 (if (zerop (length pcomplete-termination-string))
525 table
526 (apply-partially 'completion-table-with-terminator
527 (cons pcomplete-termination-string
528 "\\`a\\`")
529 table))
530 pred))))
532 ;;; Pcomplete's native UI.
534 ;;;###autoload
535 (defun pcomplete (&optional interactively)
536 "Support extensible programmable completion.
537 To use this function, just bind the TAB key to it, or add it to your
538 completion functions list (it should occur fairly early in the list)."
539 (interactive "p")
540 (if (and interactively
541 pcomplete-cycle-completions
542 pcomplete-current-completions
543 (memq last-command '(pcomplete
544 pcomplete-expand-and-complete
545 pcomplete-reverse)))
546 (progn
547 (delete-backward-char pcomplete-last-completion-length)
548 (if (eq this-command 'pcomplete-reverse)
549 (progn
550 (push (car (last pcomplete-current-completions))
551 pcomplete-current-completions)
552 (setcdr (last pcomplete-current-completions 2) nil))
553 (nconc pcomplete-current-completions
554 (list (car pcomplete-current-completions)))
555 (setq pcomplete-current-completions
556 (cdr pcomplete-current-completions)))
557 (pcomplete-insert-entry pcomplete-last-completion-stub
558 (car pcomplete-current-completions)
559 nil pcomplete-last-completion-raw))
560 (setq pcomplete-current-completions nil
561 pcomplete-last-completion-raw nil)
562 (catch 'pcompleted
563 (let* ((pcomplete-stub)
564 pcomplete-seen pcomplete-norm-func
565 pcomplete-args pcomplete-last pcomplete-index
566 (pcomplete-autolist pcomplete-autolist)
567 (pcomplete-suffix-list pcomplete-suffix-list)
568 (completions (pcomplete-completions))
569 (result (pcomplete-do-complete pcomplete-stub completions)))
570 (and result
571 (not (eq (car result) 'listed))
572 (cdr result)
573 (pcomplete-insert-entry pcomplete-stub (cdr result)
574 (memq (car result)
575 '(sole shortest))
576 pcomplete-last-completion-raw))))))
578 ;;;###autoload
579 (defun pcomplete-reverse ()
580 "If cycling completion is in use, cycle backwards."
581 (interactive)
582 (call-interactively 'pcomplete))
584 ;;;###autoload
585 (defun pcomplete-expand-and-complete ()
586 "Expand the textual value of the current argument.
587 This will modify the current buffer."
588 (interactive)
589 (let ((pcomplete-expand-before-complete t))
590 (pcomplete)))
592 ;;;###autoload
593 (defun pcomplete-continue ()
594 "Complete without reference to any cycling completions."
595 (interactive)
596 (setq pcomplete-current-completions nil
597 pcomplete-last-completion-raw nil)
598 (call-interactively 'pcomplete))
600 ;;;###autoload
601 (defun pcomplete-expand ()
602 "Expand the textual value of the current argument.
603 This will modify the current buffer."
604 (interactive)
605 (let ((pcomplete-expand-before-complete t)
606 (pcomplete-expand-only-p t))
607 (pcomplete)
608 (when (and pcomplete-current-completions
609 (> (length pcomplete-current-completions) 0)) ;??
610 (delete-backward-char pcomplete-last-completion-length)
611 (while pcomplete-current-completions
612 (unless (pcomplete-insert-entry
613 "" (car pcomplete-current-completions) t
614 pcomplete-last-completion-raw)
615 (insert-and-inherit pcomplete-termination-string))
616 (setq pcomplete-current-completions
617 (cdr pcomplete-current-completions))))))
619 ;;;###autoload
620 (defun pcomplete-help ()
621 "Display any help information relative to the current argument."
622 (interactive)
623 (let ((pcomplete-show-help t))
624 (pcomplete)))
626 ;;;###autoload
627 (defun pcomplete-list ()
628 "Show the list of possible completions for the current argument."
629 (interactive)
630 (when (and pcomplete-cycle-completions
631 pcomplete-current-completions
632 (eq last-command 'pcomplete-argument))
633 (delete-backward-char pcomplete-last-completion-length)
634 (setq pcomplete-current-completions nil
635 pcomplete-last-completion-raw nil))
636 (let ((pcomplete-show-list t))
637 (pcomplete)))
639 ;;; Internal Functions:
641 ;; argument handling
643 ;; for the sake of the bye-compiler, when compiling other files that
644 ;; contain completion functions
645 (defvar pcomplete-args nil)
646 (defvar pcomplete-begins nil)
647 (defvar pcomplete-last nil)
648 (defvar pcomplete-index nil)
649 (defvar pcomplete-stub nil)
650 (defvar pcomplete-seen nil)
651 (defvar pcomplete-norm-func nil)
653 (defun pcomplete-arg (&optional index offset)
654 "Return the textual content of the INDEXth argument.
655 INDEX is based from the current processing position. If INDEX is
656 positive, values returned are closer to the command argument; if
657 negative, they are closer to the last argument. If the INDEX is
658 outside of the argument list, nil is returned. The default value for
659 INDEX is 0, meaning the current argument being examined.
661 The special indices `first' and `last' may be used to access those
662 parts of the list.
664 The OFFSET argument is added to/taken away from the index that will be
665 used. This is really only useful with `first' and `last', for
666 accessing absolute argument positions."
667 (setq index
668 (if (eq index 'first)
670 (if (eq index 'last)
671 pcomplete-last
672 (- pcomplete-index (or index 0)))))
673 (if offset
674 (setq index (+ index offset)))
675 (nth index pcomplete-args))
677 (defun pcomplete-begin (&optional index offset)
678 "Return the beginning position of the INDEXth argument.
679 See the documentation for `pcomplete-arg'."
680 (setq index
681 (if (eq index 'first)
683 (if (eq index 'last)
684 pcomplete-last
685 (- pcomplete-index (or index 0)))))
686 (if offset
687 (setq index (+ index offset)))
688 (nth index pcomplete-begins))
690 (defsubst pcomplete-actual-arg (&optional index offset)
691 "Return the actual text representation of the last argument.
692 This is different from `pcomplete-arg', which returns the textual value
693 that the last argument evaluated to. This function returns what the
694 user actually typed in."
695 (buffer-substring (pcomplete-begin index offset) (point)))
697 (defsubst pcomplete-next-arg ()
698 "Move the various pointers to the next argument."
699 (setq pcomplete-index (1+ pcomplete-index)
700 pcomplete-stub (pcomplete-arg))
701 (if (> pcomplete-index pcomplete-last)
702 (progn
703 (message "No completions")
704 (throw 'pcompleted nil))))
706 (defun pcomplete-command-name ()
707 "Return the command name of the first argument."
708 (file-name-nondirectory (pcomplete-arg 'first)))
710 (defun pcomplete-match (regexp &optional index offset start)
711 "Like `string-match', but on the current completion argument."
712 (let ((arg (pcomplete-arg (or index 1) offset)))
713 (if arg
714 (string-match regexp arg start)
715 (throw 'pcompleted nil))))
717 (defun pcomplete-match-string (which &optional index offset)
718 "Like `match-string', but on the current completion argument."
719 (let ((arg (pcomplete-arg (or index 1) offset)))
720 (if arg
721 (match-string which arg)
722 (throw 'pcompleted nil))))
724 (defalias 'pcomplete-match-beginning 'match-beginning)
725 (defalias 'pcomplete-match-end 'match-end)
727 (defsubst pcomplete--test (pred arg)
728 "Perform a programmable completion predicate match."
729 (and pred
730 (cond ((eq pred t) t)
731 ((functionp pred)
732 (funcall pred arg))
733 ((stringp pred)
734 (string-match (concat "^" pred "$") arg)))
735 pred))
737 (defun pcomplete-test (predicates &optional index offset)
738 "Predicates to test the current programmable argument with."
739 (let ((arg (pcomplete-arg (or index 1) offset)))
740 (unless (null predicates)
741 (if (not (listp predicates))
742 (pcomplete--test predicates arg)
743 (let ((pred predicates)
744 found)
745 (while (and pred (not found))
746 (setq found (pcomplete--test (car pred) arg)
747 pred (cdr pred)))
748 found)))))
750 (defun pcomplete-parse-buffer-arguments ()
751 "Parse whitespace separated arguments in the current region."
752 (let ((begin (point-min))
753 (end (point-max))
754 begins args)
755 (save-excursion
756 (goto-char begin)
757 (while (< (point) end)
758 (skip-chars-forward " \t\n")
759 (push (point) begins)
760 (skip-chars-forward "^ \t\n")
761 (push (buffer-substring-no-properties
762 (car begins) (point))
763 args))
764 (cons (nreverse args) (nreverse begins)))))
766 ;;;###autoload
767 (defun pcomplete-comint-setup (completef-sym)
768 "Setup a comint buffer to use pcomplete.
769 COMPLETEF-SYM should be the symbol where the
770 dynamic-complete-functions are kept. For comint mode itself,
771 this is `comint-dynamic-complete-functions'."
772 (set (make-local-variable 'pcomplete-parse-arguments-function)
773 'pcomplete-parse-comint-arguments)
774 (set (make-local-variable completef-sym)
775 (copy-sequence (symbol-value completef-sym)))
776 (let* ((funs (symbol-value completef-sym))
777 (elem (or (memq 'shell-dynamic-complete-filename funs)
778 (memq 'comint-dynamic-complete-filename funs))))
779 (if elem
780 (setcar elem 'pcomplete)
781 (add-to-list completef-sym 'pcomplete))))
783 ;;;###autoload
784 (defun pcomplete-shell-setup ()
785 "Setup `shell-mode' to use pcomplete."
786 ;; FIXME: insufficient
787 (pcomplete-comint-setup 'comint-dynamic-complete-functions))
789 (declare-function comint-bol "comint" (&optional arg))
791 (defun pcomplete-parse-comint-arguments ()
792 "Parse whitespace separated arguments in the current region."
793 (let ((begin (save-excursion (comint-bol nil) (point)))
794 (end (point))
795 begins args)
796 (save-excursion
797 (goto-char begin)
798 (while (< (point) end)
799 (skip-chars-forward " \t\n")
800 (push (point) begins)
801 (let ((skip t))
802 (while skip
803 (skip-chars-forward "^ \t\n")
804 (if (eq (char-before) ?\\)
805 (skip-chars-forward " \t\n")
806 (setq skip nil))))
807 (push (buffer-substring-no-properties (car begins) (point))
808 args))
809 (cons (nreverse args) (nreverse begins)))))
811 (defun pcomplete-parse-arguments (&optional expand-p)
812 "Parse the command line arguments. Most completions need this info."
813 (let ((results (funcall pcomplete-parse-arguments-function)))
814 (when results
815 (setq pcomplete-args (or (car results) (list ""))
816 pcomplete-begins (or (cdr results) (list (point)))
817 pcomplete-last (1- (length pcomplete-args))
818 pcomplete-index 0
819 pcomplete-stub (pcomplete-arg 'last))
820 (let ((begin (pcomplete-begin 'last)))
821 (if (and pcomplete-cycle-completions
822 (listp pcomplete-stub) ;??
823 (not pcomplete-expand-only-p))
824 (let* ((completions pcomplete-stub) ;??
825 (common-stub (car completions))
826 (c completions)
827 (len (length common-stub)))
828 (while (and c (> len 0))
829 (while (and (> len 0)
830 (not (string=
831 (substring common-stub 0 len)
832 (substring (car c) 0
833 (min (length (car c))
834 len)))))
835 (setq len (1- len)))
836 (setq c (cdr c)))
837 (setq pcomplete-stub (substring common-stub 0 len)
838 pcomplete-autolist t)
839 (when (and begin (not pcomplete-show-list))
840 (delete-region begin (point))
841 (pcomplete-insert-entry "" pcomplete-stub))
842 (throw 'pcomplete-completions completions))
843 (when expand-p
844 (if (stringp pcomplete-stub)
845 (when begin
846 (delete-region begin (point))
847 (insert-and-inherit pcomplete-stub))
848 (if (and (listp pcomplete-stub)
849 pcomplete-expand-only-p)
850 ;; this is for the benefit of `pcomplete-expand'
851 (setq pcomplete-last-completion-length (- (point) begin)
852 pcomplete-current-completions pcomplete-stub)
853 (error "Cannot expand argument"))))
854 (if pcomplete-expand-only-p
855 (throw 'pcompleted t)
856 pcomplete-args))))))
858 (defun pcomplete-quote-argument (filename)
859 "Return FILENAME with magic characters quoted.
860 Magic characters are those in `pcomplete-arg-quote-list'."
861 (if (null pcomplete-arg-quote-list)
862 filename
863 (let ((index 0))
864 (mapconcat (lambda (c)
865 (prog1
866 (or (run-hook-with-args-until-success
867 'pcomplete-quote-arg-hook filename index)
868 (when (memq c pcomplete-arg-quote-list)
869 (string "\\" c))
870 (char-to-string c))
871 (setq index (1+ index))))
872 filename
873 ""))))
875 ;; file-system completion lists
877 (defsubst pcomplete-dirs-or-entries (&optional regexp predicate)
878 "Return either directories, or qualified entries."
879 ;; FIXME: pcomplete-entries doesn't return a list any more.
880 (pcomplete-entries
882 (lexical-let ((re regexp)
883 (pred predicate))
884 (lambda (f)
885 (or (file-directory-p f)
886 (and (if (not re) t (string-match re f))
887 (if (not pred) t (funcall pred f))))))))
889 (defun pcomplete-entries (&optional regexp predicate)
890 "Complete against a list of directory candidates.
891 If REGEXP is non-nil, it is a regular expression used to refine the
892 match (files not matching the REGEXP will be excluded).
893 If PREDICATE is non-nil, it will also be used to refine the match
894 \(files for which the PREDICATE returns nil will be excluded).
895 If no directory information can be extracted from the completed
896 component, `default-directory' is used as the basis for completion."
897 (let* ((name (substitute-env-vars pcomplete-stub))
898 (completion-ignore-case pcomplete-ignore-case)
899 (default-directory (expand-file-name
900 (or (file-name-directory name)
901 default-directory)))
902 above-cutoff)
903 (setq name (file-name-nondirectory name)
904 pcomplete-stub name)
905 (let ((completions
906 (file-name-all-completions name default-directory)))
907 (if regexp
908 (setq completions
909 (pcomplete-pare-list
910 completions nil
911 (function
912 (lambda (file)
913 (not (string-match regexp file)))))))
914 (if predicate
915 (setq completions
916 (pcomplete-pare-list
917 completions nil
918 (function
919 (lambda (file)
920 (not (funcall predicate file)))))))
921 (if (or pcomplete-file-ignore pcomplete-dir-ignore)
922 (setq completions
923 (pcomplete-pare-list
924 completions nil
925 (function
926 (lambda (file)
927 (if (eq (aref file (1- (length file)))
929 (and pcomplete-dir-ignore
930 (string-match pcomplete-dir-ignore file))
931 (and pcomplete-file-ignore
932 (string-match pcomplete-file-ignore file))))))))
933 (setq above-cutoff (and pcomplete-cycle-cutoff-length
934 (> (length completions)
935 pcomplete-cycle-cutoff-length)))
936 (sort completions
937 (function
938 (lambda (l r)
939 ;; for the purposes of comparison, remove the
940 ;; trailing slash from directory names.
941 ;; Otherwise, "foo.old/" will come before "foo/",
942 ;; since . is earlier in the ASCII alphabet than
943 ;; /
944 (let ((left (if (eq (aref l (1- (length l)))
946 (substring l 0 (1- (length l)))
948 (right (if (eq (aref r (1- (length r)))
950 (substring r 0 (1- (length r)))
951 r)))
952 (if above-cutoff
953 (string-lessp left right)
954 (funcall pcomplete-compare-entry-function
955 left right)))))))))
957 (defsubst pcomplete-all-entries (&optional regexp predicate)
958 "Like `pcomplete-entries', but doesn't ignore any entries."
959 (let (pcomplete-file-ignore
960 pcomplete-dir-ignore)
961 (pcomplete-entries regexp predicate)))
963 (defsubst pcomplete-dirs (&optional regexp)
964 "Complete amongst a list of directories."
965 (pcomplete-entries regexp 'file-directory-p))
967 ;; generation of completion lists
969 (defun pcomplete-find-completion-function (command)
970 "Find the completion function to call for the given COMMAND."
971 (let ((sym (intern-soft
972 (concat "pcomplete/" (symbol-name major-mode) "/" command))))
973 (unless sym
974 (setq sym (intern-soft (concat "pcomplete/" command))))
975 (and sym (fboundp sym) sym)))
977 (defun pcomplete-completions ()
978 "Return a list of completions for the current argument position."
979 (catch 'pcomplete-completions
980 (when (pcomplete-parse-arguments pcomplete-expand-before-complete)
981 (if (= pcomplete-index pcomplete-last)
982 (funcall pcomplete-command-completion-function)
983 (let ((sym (or (pcomplete-find-completion-function
984 (funcall pcomplete-command-name-function))
985 pcomplete-default-completion-function)))
986 (ignore
987 (pcomplete-next-arg)
988 (funcall sym)))))))
990 (defun pcomplete-opt (options &optional prefix no-ganging args-follow)
991 "Complete a set of OPTIONS, each beginning with PREFIX (?- by default).
992 PREFIX may be t, in which case no PREFIX character is necessary.
993 If NO-GANGING is non-nil, each option is separate (-xy is not allowed).
994 If ARGS-FOLLOW is non-nil, then options which take arguments may have
995 the argument appear after a ganged set of options. This is how tar
996 behaves, for example."
997 (if (and (= pcomplete-index pcomplete-last)
998 (string= (pcomplete-arg) "-"))
999 (let ((len (length options))
1000 (index 0)
1001 char choices)
1002 (while (< index len)
1003 (setq char (aref options index))
1004 (if (eq char ?\()
1005 (let ((result (read-from-string options index)))
1006 (setq index (cdr result)))
1007 (unless (memq char '(?/ ?* ?? ?.))
1008 (push (char-to-string char) choices))
1009 (setq index (1+ index))))
1010 (throw 'pcomplete-completions
1011 (mapcar
1012 (function
1013 (lambda (opt)
1014 (concat "-" opt)))
1015 (pcomplete-uniqify-list choices))))
1016 (let ((arg (pcomplete-arg)))
1017 (when (and (> (length arg) 1)
1018 (stringp arg)
1019 (eq (aref arg 0) (or prefix ?-)))
1020 (pcomplete-next-arg)
1021 (let ((char (aref arg 1))
1022 (len (length options))
1023 (index 0)
1024 opt-char arg-char result)
1025 (while (< (1+ index) len)
1026 (setq opt-char (aref options index)
1027 arg-char (aref options (1+ index)))
1028 (if (eq arg-char ?\()
1029 (setq result
1030 (read-from-string options (1+ index))
1031 index (cdr result)
1032 result (car result))
1033 (setq result nil))
1034 (when (and (eq char opt-char)
1035 (memq arg-char '(?\( ?/ ?* ?? ?.)))
1036 (if (< pcomplete-index pcomplete-last)
1037 (pcomplete-next-arg)
1038 (throw 'pcomplete-completions
1039 (cond ((eq arg-char ?/) (pcomplete-dirs))
1040 ((eq arg-char ?*) (pcomplete-executables))
1041 ((eq arg-char ??) nil)
1042 ((eq arg-char ?.) (pcomplete-entries))
1043 ((eq arg-char ?\() (eval result))))))
1044 (setq index (1+ index))))))))
1046 (defun pcomplete--here (&optional form stub paring form-only)
1047 "Complete against the current argument, if at the end.
1048 See the documentation for `pcomplete-here'."
1049 (if (< pcomplete-index pcomplete-last)
1050 (progn
1051 (if (eq paring 0)
1052 (setq pcomplete-seen nil)
1053 (unless (eq paring t)
1054 (let ((arg (pcomplete-arg)))
1055 (when (stringp arg)
1056 (push (if paring
1057 (funcall paring arg)
1058 (file-truename arg))
1059 pcomplete-seen)))))
1060 (pcomplete-next-arg)
1062 (when pcomplete-show-help
1063 (pcomplete--help)
1064 (throw 'pcompleted t))
1065 (if stub
1066 (setq pcomplete-stub stub))
1067 (if (or (eq paring t) (eq paring 0))
1068 (setq pcomplete-seen nil)
1069 (setq pcomplete-norm-func (or paring 'file-truename)))
1070 (unless form-only
1071 (run-hooks 'pcomplete-try-first-hook))
1072 (throw 'pcomplete-completions
1073 (if (functionp form)
1074 (funcall form)
1075 ;; Old calling convention, might still be used by files
1076 ;; byte-compiled with the older code.
1077 (eval form)))))
1079 (defmacro pcomplete-here (&optional form stub paring form-only)
1080 "Complete against the current argument, if at the end.
1081 If completion is to be done here, evaluate FORM to generate the completion
1082 table which will be used for completion purposes. If STUB is a
1083 string, use it as the completion stub instead of the default (which is
1084 the entire text of the current argument).
1086 For an example of when you might want to use STUB: if the current
1087 argument text is 'long-path-name/', you don't want the completions
1088 list display to be cluttered by 'long-path-name/' appearing at the
1089 beginning of every alternative. Not only does this make things less
1090 intelligible, but it is also inefficient. Yet, if the completion list
1091 does not begin with this string for every entry, the current argument
1092 won't complete correctly.
1094 The solution is to specify a relative stub. It allows you to
1095 substitute a different argument from the current argument, almost
1096 always for the sake of efficiency.
1098 If PARING is nil, this argument will be pared against previous
1099 arguments using the function `file-truename' to normalize them.
1100 PARING may be a function, in which case that function is used for
1101 normalization. If PARING is t, the argument dealt with by this
1102 call will not participate in argument paring. If it is the
1103 integer 0, all previous arguments that have been seen will be
1104 cleared.
1106 If FORM-ONLY is non-nil, only the result of FORM will be used to
1107 generate the completions list. This means that the hook
1108 `pcomplete-try-first-hook' will not be run."
1109 (declare (debug t))
1110 `(pcomplete--here (lambda () ,form) ,stub ,paring ,form-only))
1113 (defmacro pcomplete-here* (&optional form stub form-only)
1114 "An alternate form which does not participate in argument paring."
1115 (declare (debug t))
1116 `(pcomplete-here (lambda () ,form) ,stub t ,form-only))
1118 ;; display support
1120 (defun pcomplete-restore-windows ()
1121 "If the only window change was due to Completions, restore things."
1122 (if pcomplete-last-window-config
1123 (let* ((cbuf (get-buffer "*Completions*"))
1124 (cwin (and cbuf (get-buffer-window cbuf))))
1125 (when (window-live-p cwin)
1126 (bury-buffer cbuf)
1127 (set-window-configuration pcomplete-last-window-config))))
1128 (setq pcomplete-last-window-config nil
1129 pcomplete-window-restore-timer nil))
1131 ;; Abstractions so that the code below will work for both Emacs 20 and
1132 ;; XEmacs 21
1134 (defalias 'pcomplete-event-matches-key-specifier-p
1135 (if (featurep 'xemacs)
1136 'event-matches-key-specifier-p
1137 'eq))
1139 (defun pcomplete-read-event (&optional prompt)
1140 (if (fboundp 'read-event)
1141 (read-event prompt)
1142 (aref (read-key-sequence prompt) 0)))
1144 (defun pcomplete-show-completions (completions)
1145 "List in help buffer sorted COMPLETIONS.
1146 Typing SPC flushes the help buffer."
1147 (when pcomplete-window-restore-timer
1148 (cancel-timer pcomplete-window-restore-timer)
1149 (setq pcomplete-window-restore-timer nil))
1150 (unless pcomplete-last-window-config
1151 (setq pcomplete-last-window-config (current-window-configuration)))
1152 (with-output-to-temp-buffer "*Completions*"
1153 (display-completion-list completions))
1154 (message "Hit space to flush")
1155 (let (event)
1156 (prog1
1157 (catch 'done
1158 (while (with-current-buffer (get-buffer "*Completions*")
1159 (setq event (pcomplete-read-event)))
1160 (cond
1161 ((pcomplete-event-matches-key-specifier-p event ?\s)
1162 (set-window-configuration pcomplete-last-window-config)
1163 (setq pcomplete-last-window-config nil)
1164 (throw 'done nil))
1165 ((or (pcomplete-event-matches-key-specifier-p event 'tab)
1166 ;; Needed on a terminal
1167 (pcomplete-event-matches-key-specifier-p event 9))
1168 (let ((win (or (get-buffer-window "*Completions*" 0)
1169 (display-buffer "*Completions*"
1170 'not-this-window))))
1171 (with-selected-window win
1172 (if (pos-visible-in-window-p (point-max))
1173 (goto-char (point-min))
1174 (scroll-up))))
1175 (message ""))
1177 (setq unread-command-events (list event))
1178 (throw 'done nil)))))
1179 (if (and pcomplete-last-window-config
1180 pcomplete-restore-window-delay)
1181 (setq pcomplete-window-restore-timer
1182 (run-with-timer pcomplete-restore-window-delay nil
1183 'pcomplete-restore-windows))))))
1185 ;; insert completion at point
1187 (defun pcomplete-insert-entry (stub entry &optional addsuffix raw-p)
1188 "Insert a completion entry at point.
1189 Returns non-nil if a space was appended at the end."
1190 (let ((here (point)))
1191 (if (not pcomplete-ignore-case)
1192 (insert-and-inherit (if raw-p
1193 (substring entry (length stub))
1194 (pcomplete-quote-argument
1195 (substring entry (length stub)))))
1196 ;; the stub is not quoted at this time, so to determine the
1197 ;; length of what should be in the buffer, we must quote it
1198 ;; FIXME: Here we presume that quoting `stub' gives us the exact
1199 ;; text in the buffer before point, which is not guaranteed;
1200 ;; e.g. it is not the case in eshell when completing ${FOO}tm[TAB].
1201 (delete-backward-char (length (pcomplete-quote-argument stub)))
1202 ;; if there is already a backslash present to handle the first
1203 ;; character, don't bother quoting it
1204 (when (eq (char-before) ?\\)
1205 (insert-and-inherit (substring entry 0 1))
1206 (setq entry (substring entry 1)))
1207 (insert-and-inherit (if raw-p
1208 entry
1209 (pcomplete-quote-argument entry))))
1210 (let (space-added)
1211 (when (and (not (memq (char-before) pcomplete-suffix-list))
1212 addsuffix)
1213 (insert-and-inherit pcomplete-termination-string)
1214 (setq space-added t))
1215 (setq pcomplete-last-completion-length (- (point) here)
1216 pcomplete-last-completion-stub stub)
1217 space-added)))
1219 ;; selection of completions
1221 (defun pcomplete-do-complete (stub completions)
1222 "Dynamically complete at point using STUB and COMPLETIONS.
1223 This is basically just a wrapper for `pcomplete-stub' which does some
1224 extra checking, and munging of the COMPLETIONS list."
1225 (unless (stringp stub)
1226 (message "Cannot complete argument")
1227 (throw 'pcompleted nil))
1228 (if (null completions)
1229 (ignore
1230 (if (and stub (> (length stub) 0))
1231 (message "No completions of %s" stub)
1232 (message "No completions")))
1233 ;; pare it down, if applicable
1234 (when (and pcomplete-use-paring pcomplete-seen)
1235 (setq pcomplete-seen
1236 (mapcar 'directory-file-name pcomplete-seen))
1237 (dolist (p pcomplete-seen)
1238 (add-to-list 'pcomplete-seen
1239 (funcall pcomplete-norm-func p)))
1240 (setq completions
1241 (apply-partially 'completion-table-with-predicate
1242 completions
1243 (lambda (f)
1244 (not (member
1245 (funcall pcomplete-norm-func
1246 (directory-file-name f))
1247 pcomplete-seen)))
1248 'strict)))
1249 ;; OK, we've got a list of completions.
1250 (if pcomplete-show-list
1251 ;; FIXME: pay attention to boundaries.
1252 (pcomplete-show-completions (all-completions stub completions))
1253 (pcomplete-stub stub completions))))
1255 (defun pcomplete-stub (stub candidates &optional cycle-p)
1256 "Dynamically complete STUB from CANDIDATES list.
1257 This function inserts completion characters at point by completing
1258 STUB from the strings in CANDIDATES. A completions listing may be
1259 shown in a help buffer if completion is ambiguous.
1261 Returns nil if no completion was inserted.
1262 Returns `sole' if completed with the only completion match.
1263 Returns `shortest' if completed with the shortest of the matches.
1264 Returns `partial' if completed as far as possible with the matches.
1265 Returns `listed' if a completion listing was shown.
1267 See also `pcomplete-filename'."
1268 (let* ((completion-ignore-case pcomplete-ignore-case)
1269 (completions (all-completions stub candidates))
1270 (entry (try-completion stub candidates))
1271 result)
1272 (cond
1273 ((null entry)
1274 (if (and stub (> (length stub) 0))
1275 (message "No completions of %s" stub)
1276 (message "No completions")))
1277 ((eq entry t)
1278 (setq entry stub)
1279 (message "Sole completion")
1280 (setq result 'sole))
1281 ((= 1 (length completions))
1282 (setq result 'sole))
1283 ((and pcomplete-cycle-completions
1284 (or cycle-p
1285 (not pcomplete-cycle-cutoff-length)
1286 (<= (length completions)
1287 pcomplete-cycle-cutoff-length)))
1288 (let ((bound (car (completion-boundaries stub candidates nil ""))))
1289 (unless (zerop bound)
1290 (setq completions (mapcar (lambda (c) (concat (substring stub 0 bound) c))
1291 completions)))
1292 (setq entry (car completions)
1293 pcomplete-current-completions completions)))
1294 ((and pcomplete-recexact
1295 (string-equal stub entry)
1296 (member entry completions))
1297 ;; It's not unique, but user wants shortest match.
1298 (message "Completed shortest")
1299 (setq result 'shortest))
1300 ((or pcomplete-autolist
1301 (string-equal stub entry))
1302 ;; It's not unique, list possible completions.
1303 ;; FIXME: pay attention to boundaries.
1304 (pcomplete-show-completions completions)
1305 (setq result 'listed))
1307 (message "Partially completed")
1308 (setq result 'partial)))
1309 (cons result entry)))
1311 ;; context sensitive help
1313 (defun pcomplete--help ()
1314 "Produce context-sensitive help for the current argument.
1315 If specific documentation can't be given, be generic."
1316 (if (and pcomplete-help
1317 (or (and (stringp pcomplete-help)
1318 (fboundp 'Info-goto-node))
1319 (listp pcomplete-help)))
1320 (if (listp pcomplete-help)
1321 (message "%s" (eval pcomplete-help))
1322 (save-window-excursion (info))
1323 (switch-to-buffer-other-window "*info*")
1324 (funcall (symbol-function 'Info-goto-node) pcomplete-help))
1325 (if pcomplete-man-function
1326 (let ((cmd (funcall pcomplete-command-name-function)))
1327 (if (and cmd (> (length cmd) 0))
1328 (funcall pcomplete-man-function cmd)))
1329 (message "No context-sensitive help available"))))
1331 ;; general utilities
1333 (defun pcomplete-pare-list (l r &optional pred)
1334 "Destructively remove from list L all elements matching any in list R.
1335 Test is done using `equal'.
1336 If PRED is non-nil, it is a function used for further removal.
1337 Returns the resultant list."
1338 (while (and l (or (and r (member (car l) r))
1339 (and pred
1340 (funcall pred (car l)))))
1341 (setq l (cdr l)))
1342 (let ((m l))
1343 (while m
1344 (while (and (cdr m)
1345 (or (and r (member (cadr m) r))
1346 (and pred
1347 (funcall pred (cadr m)))))
1348 (setcdr m (cddr m)))
1349 (setq m (cdr m))))
1352 (defun pcomplete-uniqify-list (l)
1353 "Sort and remove multiples in L."
1354 (setq l (sort l 'string-lessp))
1355 (let ((m l))
1356 (while m
1357 (while (and (cdr m)
1358 (string= (car m)
1359 (cadr m)))
1360 (setcdr m (cddr m)))
1361 (setq m (cdr m))))
1364 (defun pcomplete-process-result (cmd &rest args)
1365 "Call CMD using `call-process' and return the simplest result."
1366 (with-temp-buffer
1367 (apply 'call-process cmd nil t nil args)
1368 (skip-chars-backward "\n")
1369 (buffer-substring (point-min) (point))))
1371 ;; create a set of aliases which allow completion functions to be not
1372 ;; quite so verbose
1374 ;;; jww (1999-10-20): are these a good idea?
1375 ;; (defalias 'pc-here 'pcomplete-here)
1376 ;; (defalias 'pc-test 'pcomplete-test)
1377 ;; (defalias 'pc-opt 'pcomplete-opt)
1378 ;; (defalias 'pc-match 'pcomplete-match)
1379 ;; (defalias 'pc-match-string 'pcomplete-match-string)
1380 ;; (defalias 'pc-match-beginning 'pcomplete-match-beginning)
1381 ;; (defalias 'pc-match-end 'pcomplete-match-end)
1383 (provide 'pcomplete)
1385 ;; arch-tag: ae32ef2d-dbed-4244-8b0f-cf5a2a3b07a4
1386 ;;; pcomplete.el ends here