Merge changes from emacs-23 branch
[emacs.git] / lisp / pcomplete.el
blob0f4d5e42d78b6f12f08556715cbfe7993e69a739
1 ;;; pcomplete.el --- programmable completion
3 ;; Copyright (C) 1999-2011 Free Software Foundation, Inc.
5 ;; Author: John Wiegley <johnw@gnu.org>
6 ;; Keywords: processes abbrev
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
23 ;;; Commentary:
25 ;; This module provides a programmable completion facility using
26 ;; "completion functions". Each completion function is responsible
27 ;; for producing a list of possible completions relevant to the current
28 ;; argument position.
30 ;; To use pcomplete with shell-mode, for example, you will need the
31 ;; following in your .emacs file:
33 ;; (add-hook 'shell-mode-hook 'pcomplete-shell-setup)
35 ;; Most of the code below simply provides support mechanisms for
36 ;; writing completion functions. Completion functions themselves are
37 ;; very easy to write. They have few requirements beyond those of
38 ;; regular Lisp functions.
40 ;; Consider the following example, which will complete against
41 ;; filenames for the first two arguments, and directories for all
42 ;; remaining arguments:
44 ;; (defun pcomplete/my-command ()
45 ;; (pcomplete-here (pcomplete-entries))
46 ;; (pcomplete-here (pcomplete-entries))
47 ;; (while (pcomplete-here (pcomplete-dirs))))
49 ;; Here are the requirements for completion functions:
51 ;; @ They must be called "pcomplete/MAJOR-MODE/NAME", or
52 ;; "pcomplete/NAME". This is how they are looked up, using the NAME
53 ;; specified in the command argument (the argument in first
54 ;; position).
56 ;; @ They must be callable with no arguments.
58 ;; @ Their return value is ignored. If they actually return normally,
59 ;; it means no completions were available.
61 ;; @ In order to provide completions, they must throw the tag
62 ;; `pcomplete-completions'. The value must be a completion table
63 ;; (i.e. a table that can be passed to try-completion and friends)
64 ;; for the final argument.
66 ;; @ To simplify completion function logic, the tag `pcompleted' may
67 ;; be thrown with a value of nil in order to abort the function. It
68 ;; means that there were no completions available.
70 ;; When a completion function is called, the variable `pcomplete-args'
71 ;; is in scope, and contains all of the arguments specified on the
72 ;; command line. The variable `pcomplete-last' is the index of the
73 ;; last argument in that list.
75 ;; The variable `pcomplete-index' is used by the completion code to
76 ;; know which argument the completion function is currently examining.
77 ;; It always begins at 1, meaning the first argument after the command
78 ;; name.
80 ;; To facilitate writing completion logic, a special macro,
81 ;; `pcomplete-here', has been provided which does several things:
83 ;; 1. It will throw `pcompleted' (with a value of nil) whenever
84 ;; `pcomplete-index' exceeds `pcomplete-last'.
86 ;; 2. It will increment `pcomplete-index' if the final argument has
87 ;; not been reached yet.
89 ;; 3. It will evaluate the form passed to it, and throw the result
90 ;; using the `pcomplete-completions' tag, if it is called when
91 ;; `pcomplete-index' is pointing to the final argument.
93 ;; Sometimes a completion function will want to vary the possible
94 ;; completions for an argument based on the previous one. To
95 ;; facilitate tests like this, the function `pcomplete-test' and
96 ;; `pcomplete-match' are provided. Called with one argument, they
97 ;; test the value of the previous command argument. Otherwise, a
98 ;; relative index may be given as an optional second argument, where 0
99 ;; refers to the current argument, 1 the previous, 2 the one before
100 ;; that, etc. The symbols `first' and `last' specify absolute
101 ;; offsets.
103 ;; Here is an example which will only complete against directories for
104 ;; the second argument if the first argument is also a directory:
106 ;; (defun pcomplete/example ()
107 ;; (pcomplete-here (pcomplete-entries))
108 ;; (if (pcomplete-test 'file-directory-p)
109 ;; (pcomplete-here (pcomplete-dirs))
110 ;; (pcomplete-here (pcomplete-entries))))
112 ;; For generating completion lists based on directory contents, see
113 ;; the functions `pcomplete-entries', `pcomplete-dirs',
114 ;; `pcomplete-executables' and `pcomplete-all-entries'.
116 ;; Consult the documentation for `pcomplete-here' for information
117 ;; about its other arguments.
119 ;;; Code:
121 (eval-when-compile (require 'cl))
123 (defgroup pcomplete nil
124 "Programmable completion."
125 :version "21.1"
126 :group 'processes)
128 ;;; User Variables:
130 (defcustom pcomplete-file-ignore nil
131 "A regexp of filenames to be disregarded during file completion."
132 :type '(choice regexp (const :tag "None" nil))
133 :group 'pcomplete)
135 (defcustom pcomplete-dir-ignore nil
136 "A regexp of names to be disregarded during directory completion."
137 :type '(choice regexp (const :tag "None" nil))
138 :group 'pcomplete)
140 (defcustom pcomplete-ignore-case (memq system-type '(ms-dos windows-nt cygwin))
141 ;; FIXME: the doc mentions file-name completion, but the code
142 ;; seems to apply it to all completions.
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 ;;; Alternative front-end using the standard completion facilities.
355 ;; The way pcomplete-parse-arguments, pcomplete-stub, and
356 ;; pcomplete-quote-argument work only works because of some deep
357 ;; hypothesis about the way the completion work. Basically, it makes
358 ;; it pretty much impossible to have completion other than
359 ;; prefix-completion.
361 ;; pcomplete--common-quoted-suffix and pcomplete--table-subvert try to
362 ;; work around this difficulty with heuristics, but it's
363 ;; really a hack.
365 (defvar pcomplete-unquote-argument-function nil)
367 (defun pcomplete-unquote-argument (s)
368 (cond
369 (pcomplete-unquote-argument-function
370 (funcall pcomplete-unquote-argument-function s))
371 ((null pcomplete-arg-quote-list) s)
373 (replace-regexp-in-string "\\\\\\(.\\)" "\\1" s t))))
375 (defun pcomplete--common-suffix (s1 s2)
376 (assert (not (or (string-match "\n" s1) (string-match "\n" s2))))
377 ;; Since S2 is expected to be the "unquoted/expanded" version of S1,
378 ;; there shouldn't be any case difference, even if the completion is
379 ;; case-insensitive.
380 (let ((case-fold-search nil)) ;; pcomplete-ignore-case
381 (string-match ".*?\\(.*\\)\n.*\\1\\'" (concat s1 "\n" s2))
382 (- (match-end 1) (match-beginning 1))))
384 (defun pcomplete--common-quoted-suffix (s1 s2)
385 "Find the common suffix between S1 and S2 where S1 is the expanded S2.
386 S1 is expected to be the unquoted and expanded version of S1.
387 Returns (PS1 . PS2), i.e. the shortest prefixes of S1 and S2, such that
388 S1 = (concat PS1 SS1) and S2 = (concat PS2 SS2) and
389 SS1 = (unquote SS2)."
390 (let* ((cs (pcomplete--common-suffix s1 s2))
391 (ss1 (substring s1 (- (length s1) cs)))
392 (qss1 (pcomplete-quote-argument ss1))
394 (if (and (not (equal ss1 qss1))
395 (setq qc (pcomplete-quote-argument (substring ss1 0 1)))
396 (eq t (compare-strings s2 (- (length s2) cs (length qc) -1)
397 (- (length s2) cs -1)
398 qc nil nil)))
399 ;; The difference found is just that one char is quoted in S2
400 ;; but not in S1, keep looking before this difference.
401 (pcomplete--common-quoted-suffix
402 (substring s1 0 (- (length s1) cs))
403 (substring s2 0 (- (length s2) cs (length qc) -1)))
404 (cons (substring s1 0 (- (length s1) cs))
405 (substring s2 0 (- (length s2) cs))))))
407 (defun pcomplete--table-subvert (table s1 s2 string pred action)
408 "Completion table that replaces the prefix S1 with S2 in STRING.
409 When TABLE, S1 and S2 are provided by `apply-partially', the result
410 is a completion table which completes strings of the form (concat S1 S)
411 in the same way as TABLE completes strings of the form (concat S2 S)."
412 (let* ((str (if (eq t (compare-strings string 0 (length s1) s1 nil nil
413 completion-ignore-case))
414 (concat s2 (pcomplete-unquote-argument
415 (substring string (length s1))))))
416 (res (if str (complete-with-action action table str pred))))
417 (when res
418 (cond
419 ((and (eq (car-safe action) 'boundaries))
420 (let ((beg (or (and (eq (car-safe res) 'boundaries) (cadr res)) 0)))
421 (list* 'boundaries
422 (max (length s1)
423 ;; FIXME: Adjust because of quoting/unquoting.
424 (+ beg (- (length s1) (length s2))))
425 (and (eq (car-safe res) 'boundaries) (cddr res)))))
426 ((stringp res)
427 (if (eq t (compare-strings res 0 (length s2) s2 nil nil
428 completion-ignore-case))
429 (concat s1 (pcomplete-quote-argument
430 (substring res (length s2))))))
431 ((eq action t)
432 (let ((bounds (completion-boundaries str table pred "")))
433 (if (>= (car bounds) (length s2))
435 (let ((re (concat "\\`"
436 (regexp-quote (substring s2 (car bounds))))))
437 (delq nil
438 (mapcar (lambda (c)
439 (if (string-match re c)
440 (substring c (match-end 0))))
441 res))))))))))
443 ;; I don't think such commands are usable before first setting up buffer-local
444 ;; variables to parse args, so there's no point autoloading it.
445 ;; ;;;###autoload
446 (defun pcomplete-completions-at-point ()
447 "Provide standard completion using pcomplete's completion tables.
448 Same as `pcomplete' but using the standard completion UI."
449 ;; FIXME: it only completes the text before point, whereas the
450 ;; standard UI may also consider text after point.
451 ;; FIXME: the `pcomplete' UI may be used internally during
452 ;; pcomplete-completions and then throw to `pcompleted', thus
453 ;; imposing the pcomplete UI over the standard UI.
454 (catch 'pcompleted
455 (let* ((pcomplete-stub)
456 pcomplete-seen pcomplete-norm-func
457 pcomplete-args pcomplete-last pcomplete-index
458 (pcomplete-autolist pcomplete-autolist)
459 (pcomplete-suffix-list pcomplete-suffix-list)
460 ;; Apparently the vars above are global vars modified by
461 ;; side-effects, whereas pcomplete-completions is the core
462 ;; function that finds the chunk of text to complete
463 ;; (returned indirectly in pcomplete-stub) and the set of
464 ;; possible completions.
465 (completions (pcomplete-completions))
466 ;; Usually there's some close connection between pcomplete-stub
467 ;; and the text before point. But depending on what
468 ;; pcomplete-parse-arguments-function does, that connection
469 ;; might not be that close. E.g. in eshell,
470 ;; pcomplete-parse-arguments-function expands envvars.
472 ;; Since we use minibuffer-complete, which doesn't know
473 ;; pcomplete-stub and works from the buffer's text instead,
474 ;; we need to trick minibuffer-complete, into using
475 ;; pcomplete-stub without its knowledge. To that end, we
476 ;; use pcomplete--table-subvert to construct a completion
477 ;; table which expects strings using a prefix from the
478 ;; buffer's text but internally uses the corresponding
479 ;; prefix from pcomplete-stub.
480 (beg (max (- (point) (length pcomplete-stub))
481 (pcomplete-begin)))
482 (buftext (buffer-substring beg (point)))
483 (table
484 (cond
485 ((null completions) nil)
486 ((not (equal pcomplete-stub buftext))
487 ;; This isn't always strictly right (e.g. if
488 ;; FOO="toto/$FOO", then completion of /$FOO/bar may
489 ;; result in something incorrect), but given the lack of
490 ;; any other info, it's about as good as it gets, and in
491 ;; practice it should work just fine (fingers crossed).
492 (let ((prefixes (pcomplete--common-quoted-suffix
493 pcomplete-stub buftext)))
494 (apply-partially
495 'pcomplete--table-subvert
496 completions
497 (cdr prefixes) (car prefixes))))
499 (lexical-let ((completions completions))
500 (lambda (string pred action)
501 (let ((res (complete-with-action
502 action completions string pred)))
503 (if (stringp res)
504 (pcomplete-quote-argument res)
505 res)))))))
506 (pred
507 ;; pare it down, if applicable
508 (when (and table pcomplete-use-paring pcomplete-seen)
509 (setq pcomplete-seen
510 (mapcar (lambda (f)
511 (funcall pcomplete-norm-func
512 (directory-file-name f)))
513 pcomplete-seen))
514 (lambda (f)
515 (not (member
516 (funcall pcomplete-norm-func
517 (directory-file-name f))
518 pcomplete-seen))))))
520 (list
521 beg (point)
522 ;; Add a space at the end of completion. Use a terminator-regexp
523 ;; that never matches since the terminator cannot appear
524 ;; within the completion field anyway.
525 (if (zerop (length pcomplete-termination-string))
526 table
527 (apply-partially 'completion-table-with-terminator
528 (cons pcomplete-termination-string
529 "\\`a\\`")
530 table))
531 :predicate pred))))
533 ;; I don't think such commands are usable before first setting up buffer-local
534 ;; variables to parse args, so there's no point autoloading it.
535 ;; ;;;###autoload
536 (defun pcomplete-std-complete ()
537 (let ((completion-at-point-functions '(pcomplete-completions-at-point)))
538 (completion-at-point)))
540 ;;; Pcomplete's native UI.
542 ;;;###autoload
543 (defun pcomplete (&optional interactively)
544 "Support extensible programmable completion.
545 To use this function, just bind the TAB key to it, or add it to your
546 completion functions list (it should occur fairly early in the list)."
547 (interactive "p")
548 (if (and interactively
549 pcomplete-cycle-completions
550 pcomplete-current-completions
551 (memq last-command '(pcomplete
552 pcomplete-expand-and-complete
553 pcomplete-reverse)))
554 (progn
555 (delete-char (- pcomplete-last-completion-length))
556 (if (eq this-command 'pcomplete-reverse)
557 (progn
558 (push (car (last pcomplete-current-completions))
559 pcomplete-current-completions)
560 (setcdr (last pcomplete-current-completions 2) nil))
561 (nconc pcomplete-current-completions
562 (list (car pcomplete-current-completions)))
563 (setq pcomplete-current-completions
564 (cdr pcomplete-current-completions)))
565 (pcomplete-insert-entry pcomplete-last-completion-stub
566 (car pcomplete-current-completions)
567 nil pcomplete-last-completion-raw))
568 (setq pcomplete-current-completions nil
569 pcomplete-last-completion-raw nil)
570 (catch 'pcompleted
571 (let* ((pcomplete-stub)
572 pcomplete-seen pcomplete-norm-func
573 pcomplete-args pcomplete-last pcomplete-index
574 (pcomplete-autolist pcomplete-autolist)
575 (pcomplete-suffix-list pcomplete-suffix-list)
576 (completions (pcomplete-completions))
577 (result (pcomplete-do-complete pcomplete-stub completions)))
578 (and result
579 (not (eq (car result) 'listed))
580 (cdr result)
581 (pcomplete-insert-entry pcomplete-stub (cdr result)
582 (memq (car result)
583 '(sole shortest))
584 pcomplete-last-completion-raw))))))
586 ;;;###autoload
587 (defun pcomplete-reverse ()
588 "If cycling completion is in use, cycle backwards."
589 (interactive)
590 (call-interactively 'pcomplete))
592 ;;;###autoload
593 (defun pcomplete-expand-and-complete ()
594 "Expand the textual value of the current argument.
595 This will modify the current buffer."
596 (interactive)
597 (let ((pcomplete-expand-before-complete t))
598 (pcomplete)))
600 ;;;###autoload
601 (defun pcomplete-continue ()
602 "Complete without reference to any cycling completions."
603 (interactive)
604 (setq pcomplete-current-completions nil
605 pcomplete-last-completion-raw nil)
606 (call-interactively 'pcomplete))
608 ;;;###autoload
609 (defun pcomplete-expand ()
610 "Expand the textual value of the current argument.
611 This will modify the current buffer."
612 (interactive)
613 (let ((pcomplete-expand-before-complete t)
614 (pcomplete-expand-only-p t))
615 (pcomplete)
616 (when (and pcomplete-current-completions
617 (> (length pcomplete-current-completions) 0)) ;??
618 (delete-char (- pcomplete-last-completion-length))
619 (while pcomplete-current-completions
620 (unless (pcomplete-insert-entry
621 "" (car pcomplete-current-completions) t
622 pcomplete-last-completion-raw)
623 (insert-and-inherit pcomplete-termination-string))
624 (setq pcomplete-current-completions
625 (cdr pcomplete-current-completions))))))
627 ;;;###autoload
628 (defun pcomplete-help ()
629 "Display any help information relative to the current argument."
630 (interactive)
631 (let ((pcomplete-show-help t))
632 (pcomplete)))
634 ;;;###autoload
635 (defun pcomplete-list ()
636 "Show the list of possible completions for the current argument."
637 (interactive)
638 (when (and pcomplete-cycle-completions
639 pcomplete-current-completions
640 (eq last-command 'pcomplete-argument))
641 (delete-char (- pcomplete-last-completion-length))
642 (setq pcomplete-current-completions nil
643 pcomplete-last-completion-raw nil))
644 (let ((pcomplete-show-list t))
645 (pcomplete)))
647 ;;; Internal Functions:
649 ;; argument handling
651 ;; for the sake of the bye-compiler, when compiling other files that
652 ;; contain completion functions
653 (defvar pcomplete-args nil)
654 (defvar pcomplete-begins nil)
655 (defvar pcomplete-last nil)
656 (defvar pcomplete-index nil)
657 (defvar pcomplete-stub nil)
658 (defvar pcomplete-seen nil)
659 (defvar pcomplete-norm-func nil)
661 (defun pcomplete-arg (&optional index offset)
662 "Return the textual content of the INDEXth argument.
663 INDEX is based from the current processing position. If INDEX is
664 positive, values returned are closer to the command argument; if
665 negative, they are closer to the last argument. If the INDEX is
666 outside of the argument list, nil is returned. The default value for
667 INDEX is 0, meaning the current argument being examined.
669 The special indices `first' and `last' may be used to access those
670 parts of the list.
672 The OFFSET argument is added to/taken away from the index that will be
673 used. This is really only useful with `first' and `last', for
674 accessing absolute argument positions."
675 (setq index
676 (if (eq index 'first)
678 (if (eq index 'last)
679 pcomplete-last
680 (- pcomplete-index (or index 0)))))
681 (if offset
682 (setq index (+ index offset)))
683 (nth index pcomplete-args))
685 (defun pcomplete-begin (&optional index offset)
686 "Return the beginning position of the INDEXth argument.
687 See the documentation for `pcomplete-arg'."
688 (setq index
689 (if (eq index 'first)
691 (if (eq index 'last)
692 pcomplete-last
693 (- pcomplete-index (or index 0)))))
694 (if offset
695 (setq index (+ index offset)))
696 (nth index pcomplete-begins))
698 (defsubst pcomplete-actual-arg (&optional index offset)
699 "Return the actual text representation of the last argument.
700 This is different from `pcomplete-arg', which returns the textual value
701 that the last argument evaluated to. This function returns what the
702 user actually typed in."
703 (buffer-substring (pcomplete-begin index offset) (point)))
705 (defsubst pcomplete-next-arg ()
706 "Move the various pointers to the next argument."
707 (setq pcomplete-index (1+ pcomplete-index)
708 pcomplete-stub (pcomplete-arg))
709 (if (> pcomplete-index pcomplete-last)
710 (progn
711 (message "No completions")
712 (throw 'pcompleted nil))))
714 (defun pcomplete-command-name ()
715 "Return the command name of the first argument."
716 (file-name-nondirectory (pcomplete-arg 'first)))
718 (defun pcomplete-match (regexp &optional index offset start)
719 "Like `string-match', but on the current completion argument."
720 (let ((arg (pcomplete-arg (or index 1) offset)))
721 (if arg
722 (string-match regexp arg start)
723 (throw 'pcompleted nil))))
725 (defun pcomplete-match-string (which &optional index offset)
726 "Like `match-string', but on the current completion argument."
727 (let ((arg (pcomplete-arg (or index 1) offset)))
728 (if arg
729 (match-string which arg)
730 (throw 'pcompleted nil))))
732 (defalias 'pcomplete-match-beginning 'match-beginning)
733 (defalias 'pcomplete-match-end 'match-end)
735 (defsubst pcomplete--test (pred arg)
736 "Perform a programmable completion predicate match."
737 (and pred
738 (cond ((eq pred t) t)
739 ((functionp pred)
740 (funcall pred arg))
741 ((stringp pred)
742 (string-match (concat "^" pred "$") arg)))
743 pred))
745 (defun pcomplete-test (predicates &optional index offset)
746 "Predicates to test the current programmable argument with."
747 (let ((arg (pcomplete-arg (or index 1) offset)))
748 (unless (null predicates)
749 (if (not (listp predicates))
750 (pcomplete--test predicates arg)
751 (let ((pred predicates)
752 found)
753 (while (and pred (not found))
754 (setq found (pcomplete--test (car pred) arg)
755 pred (cdr pred)))
756 found)))))
758 (defun pcomplete-parse-buffer-arguments ()
759 "Parse whitespace separated arguments in the current region."
760 (let ((begin (point-min))
761 (end (point-max))
762 begins args)
763 (save-excursion
764 (goto-char begin)
765 (while (< (point) end)
766 (skip-chars-forward " \t\n")
767 (push (point) begins)
768 (skip-chars-forward "^ \t\n")
769 (push (buffer-substring-no-properties
770 (car begins) (point))
771 args))
772 (cons (nreverse args) (nreverse begins)))))
774 ;;;###autoload
775 (defun pcomplete-comint-setup (completef-sym)
776 "Setup a comint buffer to use pcomplete.
777 COMPLETEF-SYM should be the symbol where the
778 dynamic-complete-functions are kept. For comint mode itself,
779 this is `comint-dynamic-complete-functions'."
780 (set (make-local-variable 'pcomplete-parse-arguments-function)
781 'pcomplete-parse-comint-arguments)
782 (set (make-local-variable completef-sym)
783 (copy-sequence (symbol-value completef-sym)))
784 (let* ((funs (symbol-value completef-sym))
785 (elem (or (memq 'shell-dynamic-complete-filename funs)
786 (memq 'comint-dynamic-complete-filename funs))))
787 (if elem
788 (setcar elem 'pcomplete)
789 (add-to-list completef-sym 'pcomplete))))
791 ;;;###autoload
792 (defun pcomplete-shell-setup ()
793 "Setup `shell-mode' to use pcomplete."
794 ;; FIXME: insufficient
795 (pcomplete-comint-setup 'comint-dynamic-complete-functions))
797 (declare-function comint-bol "comint" (&optional arg))
799 (defun pcomplete-parse-comint-arguments ()
800 "Parse whitespace separated arguments in the current region."
801 (let ((begin (save-excursion (comint-bol nil) (point)))
802 (end (point))
803 begins args)
804 (save-excursion
805 (goto-char begin)
806 (while (< (point) end)
807 (skip-chars-forward " \t\n")
808 (push (point) begins)
809 (let ((skip t))
810 (while skip
811 (skip-chars-forward "^ \t\n")
812 (if (eq (char-before) ?\\)
813 (skip-chars-forward " \t\n")
814 (setq skip nil))))
815 (push (buffer-substring-no-properties (car begins) (point))
816 args))
817 (cons (nreverse args) (nreverse begins)))))
819 (defun pcomplete-parse-arguments (&optional expand-p)
820 "Parse the command line arguments. Most completions need this info."
821 (let ((results (funcall pcomplete-parse-arguments-function)))
822 (when results
823 (setq pcomplete-args (or (car results) (list ""))
824 pcomplete-begins (or (cdr results) (list (point)))
825 pcomplete-last (1- (length pcomplete-args))
826 pcomplete-index 0
827 pcomplete-stub (pcomplete-arg 'last))
828 (let ((begin (pcomplete-begin 'last)))
829 (if (and pcomplete-cycle-completions
830 (listp pcomplete-stub) ;??
831 (not pcomplete-expand-only-p))
832 (let* ((completions pcomplete-stub) ;??
833 (common-stub (car completions))
834 (c completions)
835 (len (length common-stub)))
836 (while (and c (> len 0))
837 (while (and (> len 0)
838 (not (string=
839 (substring common-stub 0 len)
840 (substring (car c) 0
841 (min (length (car c))
842 len)))))
843 (setq len (1- len)))
844 (setq c (cdr c)))
845 (setq pcomplete-stub (substring common-stub 0 len)
846 pcomplete-autolist t)
847 (when (and begin (not pcomplete-show-list))
848 (delete-region begin (point))
849 (pcomplete-insert-entry "" pcomplete-stub))
850 (throw 'pcomplete-completions completions))
851 (when expand-p
852 (if (stringp pcomplete-stub)
853 (when begin
854 (delete-region begin (point))
855 (insert-and-inherit pcomplete-stub))
856 (if (and (listp pcomplete-stub)
857 pcomplete-expand-only-p)
858 ;; this is for the benefit of `pcomplete-expand'
859 (setq pcomplete-last-completion-length (- (point) begin)
860 pcomplete-current-completions pcomplete-stub)
861 (error "Cannot expand argument"))))
862 (if pcomplete-expand-only-p
863 (throw 'pcompleted t)
864 pcomplete-args))))))
866 (defun pcomplete-quote-argument (filename)
867 "Return FILENAME with magic characters quoted.
868 Magic characters are those in `pcomplete-arg-quote-list'."
869 (if (null pcomplete-arg-quote-list)
870 filename
871 (let ((index 0))
872 (mapconcat (lambda (c)
873 (prog1
874 (or (run-hook-with-args-until-success
875 'pcomplete-quote-arg-hook filename index)
876 (when (memq c pcomplete-arg-quote-list)
877 (string "\\" c))
878 (char-to-string c))
879 (setq index (1+ index))))
880 filename
881 ""))))
883 ;; file-system completion lists
885 (defsubst pcomplete-dirs-or-entries (&optional regexp predicate)
886 "Return either directories, or qualified entries."
887 ;; FIXME: pcomplete-entries doesn't return a list any more.
888 (pcomplete-entries
890 (lexical-let ((re regexp)
891 (pred predicate))
892 (lambda (f)
893 (or (file-directory-p f)
894 (and (if (not re) t (string-match re f))
895 (if (not pred) t (funcall pred f))))))))
897 (defun pcomplete-entries (&optional regexp predicate)
898 "Complete against a list of directory candidates.
899 If REGEXP is non-nil, it is a regular expression used to refine the
900 match (files not matching the REGEXP will be excluded).
901 If PREDICATE is non-nil, it will also be used to refine the match
902 \(files for which the PREDICATE returns nil will be excluded).
903 If no directory information can be extracted from the completed
904 component, `default-directory' is used as the basis for completion."
905 (let* ((name (substitute-env-vars pcomplete-stub))
906 (completion-ignore-case pcomplete-ignore-case)
907 (default-directory (expand-file-name
908 (or (file-name-directory name)
909 default-directory)))
910 above-cutoff)
911 (setq name (file-name-nondirectory name)
912 pcomplete-stub name)
913 (let ((completions
914 (file-name-all-completions name default-directory)))
915 (if regexp
916 (setq completions
917 (pcomplete-pare-list
918 completions nil
919 (function
920 (lambda (file)
921 (not (string-match regexp file)))))))
922 (if predicate
923 (setq completions
924 (pcomplete-pare-list
925 completions nil
926 (function
927 (lambda (file)
928 (not (funcall predicate file)))))))
929 (if (or pcomplete-file-ignore pcomplete-dir-ignore)
930 (setq completions
931 (pcomplete-pare-list
932 completions nil
933 (function
934 (lambda (file)
935 (if (eq (aref file (1- (length file)))
937 (and pcomplete-dir-ignore
938 (string-match pcomplete-dir-ignore file))
939 (and pcomplete-file-ignore
940 (string-match pcomplete-file-ignore file))))))))
941 (setq above-cutoff (and pcomplete-cycle-cutoff-length
942 (> (length completions)
943 pcomplete-cycle-cutoff-length)))
944 (sort completions
945 (function
946 (lambda (l r)
947 ;; for the purposes of comparison, remove the
948 ;; trailing slash from directory names.
949 ;; Otherwise, "foo.old/" will come before "foo/",
950 ;; since . is earlier in the ASCII alphabet than
951 ;; /
952 (let ((left (if (eq (aref l (1- (length l)))
954 (substring l 0 (1- (length l)))
956 (right (if (eq (aref r (1- (length r)))
958 (substring r 0 (1- (length r)))
959 r)))
960 (if above-cutoff
961 (string-lessp left right)
962 (funcall pcomplete-compare-entry-function
963 left right)))))))))
965 (defsubst pcomplete-all-entries (&optional regexp predicate)
966 "Like `pcomplete-entries', but doesn't ignore any entries."
967 (let (pcomplete-file-ignore
968 pcomplete-dir-ignore)
969 (pcomplete-entries regexp predicate)))
971 (defsubst pcomplete-dirs (&optional regexp)
972 "Complete amongst a list of directories."
973 (pcomplete-entries regexp 'file-directory-p))
975 ;; generation of completion lists
977 (defun pcomplete-find-completion-function (command)
978 "Find the completion function to call for the given COMMAND."
979 (let ((sym (intern-soft
980 (concat "pcomplete/" (symbol-name major-mode) "/" command))))
981 (unless sym
982 (setq sym (intern-soft (concat "pcomplete/" command))))
983 (and sym (fboundp sym) sym)))
985 (defun pcomplete-completions ()
986 "Return a list of completions for the current argument position."
987 (catch 'pcomplete-completions
988 (when (pcomplete-parse-arguments pcomplete-expand-before-complete)
989 (if (= pcomplete-index pcomplete-last)
990 (funcall pcomplete-command-completion-function)
991 (let ((sym (or (pcomplete-find-completion-function
992 (funcall pcomplete-command-name-function))
993 pcomplete-default-completion-function)))
994 (ignore
995 (pcomplete-next-arg)
996 (funcall sym)))))))
998 (defun pcomplete-opt (options &optional prefix no-ganging args-follow)
999 "Complete a set of OPTIONS, each beginning with PREFIX (?- by default).
1000 PREFIX may be t, in which case no PREFIX character is necessary.
1001 If NO-GANGING is non-nil, each option is separate (-xy is not allowed).
1002 If ARGS-FOLLOW is non-nil, then options which take arguments may have
1003 the argument appear after a ganged set of options. This is how tar
1004 behaves, for example."
1005 (if (and (= pcomplete-index pcomplete-last)
1006 (string= (pcomplete-arg) "-"))
1007 (let ((len (length options))
1008 (index 0)
1009 char choices)
1010 (while (< index len)
1011 (setq char (aref options index))
1012 (if (eq char ?\()
1013 (let ((result (read-from-string options index)))
1014 (setq index (cdr result)))
1015 (unless (memq char '(?/ ?* ?? ?.))
1016 (push (char-to-string char) choices))
1017 (setq index (1+ index))))
1018 (throw 'pcomplete-completions
1019 (mapcar
1020 (function
1021 (lambda (opt)
1022 (concat "-" opt)))
1023 (pcomplete-uniqify-list choices))))
1024 (let ((arg (pcomplete-arg)))
1025 (when (and (> (length arg) 1)
1026 (stringp arg)
1027 (eq (aref arg 0) (or prefix ?-)))
1028 (pcomplete-next-arg)
1029 (let ((char (aref arg 1))
1030 (len (length options))
1031 (index 0)
1032 opt-char arg-char result)
1033 (while (< (1+ index) len)
1034 (setq opt-char (aref options index)
1035 arg-char (aref options (1+ index)))
1036 (if (eq arg-char ?\()
1037 (setq result
1038 (read-from-string options (1+ index))
1039 index (cdr result)
1040 result (car result))
1041 (setq result nil))
1042 (when (and (eq char opt-char)
1043 (memq arg-char '(?\( ?/ ?* ?? ?.)))
1044 (if (< pcomplete-index pcomplete-last)
1045 (pcomplete-next-arg)
1046 (throw 'pcomplete-completions
1047 (cond ((eq arg-char ?/) (pcomplete-dirs))
1048 ((eq arg-char ?*) (pcomplete-executables))
1049 ((eq arg-char ??) nil)
1050 ((eq arg-char ?.) (pcomplete-entries))
1051 ((eq arg-char ?\() (eval result))))))
1052 (setq index (1+ index))))))))
1054 (defun pcomplete--here (&optional form stub paring form-only)
1055 "Complete against the current argument, if at the end.
1056 See the documentation for `pcomplete-here'."
1057 (if (< pcomplete-index pcomplete-last)
1058 (progn
1059 (if (eq paring 0)
1060 (setq pcomplete-seen nil)
1061 (unless (eq paring t)
1062 (let ((arg (pcomplete-arg)))
1063 (when (stringp arg)
1064 (push (if paring
1065 (funcall paring arg)
1066 (file-truename arg))
1067 pcomplete-seen)))))
1068 (pcomplete-next-arg)
1070 (when pcomplete-show-help
1071 (pcomplete--help)
1072 (throw 'pcompleted t))
1073 (if stub
1074 (setq pcomplete-stub stub))
1075 (if (or (eq paring t) (eq paring 0))
1076 (setq pcomplete-seen nil)
1077 (setq pcomplete-norm-func (or paring 'file-truename)))
1078 (unless form-only
1079 (run-hooks 'pcomplete-try-first-hook))
1080 (throw 'pcomplete-completions
1081 (if (functionp form)
1082 (funcall form)
1083 ;; Old calling convention, might still be used by files
1084 ;; byte-compiled with the older code.
1085 (eval form)))))
1087 (defmacro pcomplete-here (&optional form stub paring form-only)
1088 "Complete against the current argument, if at the end.
1089 If completion is to be done here, evaluate FORM to generate the completion
1090 table which will be used for completion purposes. If STUB is a
1091 string, use it as the completion stub instead of the default (which is
1092 the entire text of the current argument).
1094 For an example of when you might want to use STUB: if the current
1095 argument text is 'long-path-name/', you don't want the completions
1096 list display to be cluttered by 'long-path-name/' appearing at the
1097 beginning of every alternative. Not only does this make things less
1098 intelligible, but it is also inefficient. Yet, if the completion list
1099 does not begin with this string for every entry, the current argument
1100 won't complete correctly.
1102 The solution is to specify a relative stub. It allows you to
1103 substitute a different argument from the current argument, almost
1104 always for the sake of efficiency.
1106 If PARING is nil, this argument will be pared against previous
1107 arguments using the function `file-truename' to normalize them.
1108 PARING may be a function, in which case that function is used for
1109 normalization. If PARING is t, the argument dealt with by this
1110 call will not participate in argument paring. If it is the
1111 integer 0, all previous arguments that have been seen will be
1112 cleared.
1114 If FORM-ONLY is non-nil, only the result of FORM will be used to
1115 generate the completions list. This means that the hook
1116 `pcomplete-try-first-hook' will not be run."
1117 (declare (debug t))
1118 `(pcomplete--here (lambda () ,form) ,stub ,paring ,form-only))
1121 (defmacro pcomplete-here* (&optional form stub form-only)
1122 "An alternate form which does not participate in argument paring."
1123 (declare (debug t))
1124 `(pcomplete-here ,form ,stub t ,form-only))
1126 ;; display support
1128 (defun pcomplete-restore-windows ()
1129 "If the only window change was due to Completions, restore things."
1130 (if pcomplete-last-window-config
1131 (let* ((cbuf (get-buffer "*Completions*"))
1132 (cwin (and cbuf (get-buffer-window cbuf))))
1133 (when (window-live-p cwin)
1134 (bury-buffer cbuf)
1135 (set-window-configuration pcomplete-last-window-config))))
1136 (setq pcomplete-last-window-config nil
1137 pcomplete-window-restore-timer nil))
1139 ;; Abstractions so that the code below will work for both Emacs 20 and
1140 ;; XEmacs 21
1142 (defalias 'pcomplete-event-matches-key-specifier-p
1143 (if (featurep 'xemacs)
1144 'event-matches-key-specifier-p
1145 'eq))
1147 (defun pcomplete-read-event (&optional prompt)
1148 (if (fboundp 'read-event)
1149 (read-event prompt)
1150 (aref (read-key-sequence prompt) 0)))
1152 (defun pcomplete-show-completions (completions)
1153 "List in help buffer sorted COMPLETIONS.
1154 Typing SPC flushes the help buffer."
1155 (when pcomplete-window-restore-timer
1156 (cancel-timer pcomplete-window-restore-timer)
1157 (setq pcomplete-window-restore-timer nil))
1158 (unless pcomplete-last-window-config
1159 (setq pcomplete-last-window-config (current-window-configuration)))
1160 (with-output-to-temp-buffer "*Completions*"
1161 (display-completion-list completions))
1162 (message "Hit space to flush")
1163 (let (event)
1164 (prog1
1165 (catch 'done
1166 (while (with-current-buffer (get-buffer "*Completions*")
1167 (setq event (pcomplete-read-event)))
1168 (cond
1169 ((pcomplete-event-matches-key-specifier-p event ?\s)
1170 (set-window-configuration pcomplete-last-window-config)
1171 (setq pcomplete-last-window-config nil)
1172 (throw 'done nil))
1173 ((or (pcomplete-event-matches-key-specifier-p event 'tab)
1174 ;; Needed on a terminal
1175 (pcomplete-event-matches-key-specifier-p event 9))
1176 (let ((win (or (get-buffer-window "*Completions*" 0)
1177 (display-buffer "*Completions*"
1178 'not-this-window))))
1179 (with-selected-window win
1180 (if (pos-visible-in-window-p (point-max))
1181 (goto-char (point-min))
1182 (scroll-up))))
1183 (message ""))
1185 (setq unread-command-events (list event))
1186 (throw 'done nil)))))
1187 (if (and pcomplete-last-window-config
1188 pcomplete-restore-window-delay)
1189 (setq pcomplete-window-restore-timer
1190 (run-with-timer pcomplete-restore-window-delay nil
1191 'pcomplete-restore-windows))))))
1193 ;; insert completion at point
1195 (defun pcomplete-insert-entry (stub entry &optional addsuffix raw-p)
1196 "Insert a completion entry at point.
1197 Returns non-nil if a space was appended at the end."
1198 (let ((here (point)))
1199 (if (not pcomplete-ignore-case)
1200 (insert-and-inherit (if raw-p
1201 (substring entry (length stub))
1202 (pcomplete-quote-argument
1203 (substring entry (length stub)))))
1204 ;; the stub is not quoted at this time, so to determine the
1205 ;; length of what should be in the buffer, we must quote it
1206 ;; FIXME: Here we presume that quoting `stub' gives us the exact
1207 ;; text in the buffer before point, which is not guaranteed;
1208 ;; e.g. it is not the case in eshell when completing ${FOO}tm[TAB].
1209 (delete-char (- (length (pcomplete-quote-argument stub))))
1210 ;; if there is already a backslash present to handle the first
1211 ;; character, don't bother quoting it
1212 (when (eq (char-before) ?\\)
1213 (insert-and-inherit (substring entry 0 1))
1214 (setq entry (substring entry 1)))
1215 (insert-and-inherit (if raw-p
1216 entry
1217 (pcomplete-quote-argument entry))))
1218 (let (space-added)
1219 (when (and (not (memq (char-before) pcomplete-suffix-list))
1220 addsuffix)
1221 (insert-and-inherit pcomplete-termination-string)
1222 (setq space-added t))
1223 (setq pcomplete-last-completion-length (- (point) here)
1224 pcomplete-last-completion-stub stub)
1225 space-added)))
1227 ;; selection of completions
1229 (defun pcomplete-do-complete (stub completions)
1230 "Dynamically complete at point using STUB and COMPLETIONS.
1231 This is basically just a wrapper for `pcomplete-stub' which does some
1232 extra checking, and munging of the COMPLETIONS list."
1233 (unless (stringp stub)
1234 (message "Cannot complete argument")
1235 (throw 'pcompleted nil))
1236 (if (null completions)
1237 (ignore
1238 (if (and stub (> (length stub) 0))
1239 (message "No completions of %s" stub)
1240 (message "No completions")))
1241 ;; pare it down, if applicable
1242 (when (and pcomplete-use-paring pcomplete-seen)
1243 (setq pcomplete-seen
1244 (mapcar 'directory-file-name pcomplete-seen))
1245 (dolist (p pcomplete-seen)
1246 (add-to-list 'pcomplete-seen
1247 (funcall pcomplete-norm-func p)))
1248 (setq completions
1249 (apply-partially 'completion-table-with-predicate
1250 completions
1251 (lambda (f)
1252 (not (member
1253 (funcall pcomplete-norm-func
1254 (directory-file-name f))
1255 pcomplete-seen)))
1256 'strict)))
1257 ;; OK, we've got a list of completions.
1258 (if pcomplete-show-list
1259 ;; FIXME: pay attention to boundaries.
1260 (pcomplete-show-completions (all-completions stub completions))
1261 (pcomplete-stub stub completions))))
1263 (defun pcomplete-stub (stub candidates &optional cycle-p)
1264 "Dynamically complete STUB from CANDIDATES list.
1265 This function inserts completion characters at point by completing
1266 STUB from the strings in CANDIDATES. A completions listing may be
1267 shown in a help buffer if completion is ambiguous.
1269 Returns nil if no completion was inserted.
1270 Returns `sole' if completed with the only completion match.
1271 Returns `shortest' if completed with the shortest of the matches.
1272 Returns `partial' if completed as far as possible with the matches.
1273 Returns `listed' if a completion listing was shown.
1275 See also `pcomplete-filename'."
1276 (let* ((completion-ignore-case pcomplete-ignore-case)
1277 (completions (all-completions stub candidates))
1278 (entry (try-completion stub candidates))
1279 result)
1280 (cond
1281 ((null entry)
1282 (if (and stub (> (length stub) 0))
1283 (message "No completions of %s" stub)
1284 (message "No completions")))
1285 ((eq entry t)
1286 (setq entry stub)
1287 (message "Sole completion")
1288 (setq result 'sole))
1289 ((= 1 (length completions))
1290 (setq result 'sole))
1291 ((and pcomplete-cycle-completions
1292 (or cycle-p
1293 (not pcomplete-cycle-cutoff-length)
1294 (<= (length completions)
1295 pcomplete-cycle-cutoff-length)))
1296 (let ((bound (car (completion-boundaries stub candidates nil ""))))
1297 (unless (zerop bound)
1298 (setq completions (mapcar (lambda (c) (concat (substring stub 0 bound) c))
1299 completions)))
1300 (setq entry (car completions)
1301 pcomplete-current-completions completions)))
1302 ((and pcomplete-recexact
1303 (string-equal stub entry)
1304 (member entry completions))
1305 ;; It's not unique, but user wants shortest match.
1306 (message "Completed shortest")
1307 (setq result 'shortest))
1308 ((or pcomplete-autolist
1309 (string-equal stub entry))
1310 ;; It's not unique, list possible completions.
1311 ;; FIXME: pay attention to boundaries.
1312 (pcomplete-show-completions completions)
1313 (setq result 'listed))
1315 (message "Partially completed")
1316 (setq result 'partial)))
1317 (cons result entry)))
1319 ;; context sensitive help
1321 (defun pcomplete--help ()
1322 "Produce context-sensitive help for the current argument.
1323 If specific documentation can't be given, be generic."
1324 (if (and pcomplete-help
1325 (or (and (stringp pcomplete-help)
1326 (fboundp 'Info-goto-node))
1327 (listp pcomplete-help)))
1328 (if (listp pcomplete-help)
1329 (message "%s" (eval pcomplete-help))
1330 (save-window-excursion (info))
1331 (switch-to-buffer-other-window "*info*")
1332 (funcall (symbol-function 'Info-goto-node) pcomplete-help))
1333 (if pcomplete-man-function
1334 (let ((cmd (funcall pcomplete-command-name-function)))
1335 (if (and cmd (> (length cmd) 0))
1336 (funcall pcomplete-man-function cmd)))
1337 (message "No context-sensitive help available"))))
1339 ;; general utilities
1341 (defun pcomplete-pare-list (l r &optional pred)
1342 "Destructively remove from list L all elements matching any in list R.
1343 Test is done using `equal'.
1344 If PRED is non-nil, it is a function used for further removal.
1345 Returns the resultant list."
1346 (while (and l (or (and r (member (car l) r))
1347 (and pred
1348 (funcall pred (car l)))))
1349 (setq l (cdr l)))
1350 (let ((m l))
1351 (while m
1352 (while (and (cdr m)
1353 (or (and r (member (cadr m) r))
1354 (and pred
1355 (funcall pred (cadr m)))))
1356 (setcdr m (cddr m)))
1357 (setq m (cdr m))))
1360 (defun pcomplete-uniqify-list (l)
1361 "Sort and remove multiples in L."
1362 (setq l (sort l 'string-lessp))
1363 (let ((m l))
1364 (while m
1365 (while (and (cdr m)
1366 (string= (car m)
1367 (cadr m)))
1368 (setcdr m (cddr m)))
1369 (setq m (cdr m))))
1372 (defun pcomplete-process-result (cmd &rest args)
1373 "Call CMD using `call-process' and return the simplest result."
1374 (with-temp-buffer
1375 (apply 'call-process cmd nil t nil args)
1376 (skip-chars-backward "\n")
1377 (buffer-substring (point-min) (point))))
1379 ;; create a set of aliases which allow completion functions to be not
1380 ;; quite so verbose
1382 ;;; jww (1999-10-20): are these a good idea?
1383 ;; (defalias 'pc-here 'pcomplete-here)
1384 ;; (defalias 'pc-test 'pcomplete-test)
1385 ;; (defalias 'pc-opt 'pcomplete-opt)
1386 ;; (defalias 'pc-match 'pcomplete-match)
1387 ;; (defalias 'pc-match-string 'pcomplete-match-string)
1388 ;; (defalias 'pc-match-beginning 'pcomplete-match-beginning)
1389 ;; (defalias 'pc-match-end 'pcomplete-match-end)
1391 (provide 'pcomplete)
1393 ;;; pcomplete.el ends here