1 ;;; em-cmpl.el --- completion using the TAB key
3 ;; Copyright (C) 1999-2011 Free Software Foundation, Inc.
5 ;; Author: John Wiegley <johnw@gnu.org>
7 ;; This file is part of GNU Emacs.
9 ;; GNU Emacs is free software: you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation, either version 3 of the License, or
12 ;; (at your option) any later version.
14 ;; GNU Emacs is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
24 ;; Eshell, by using the pcomplete package, provides a full
25 ;; programmable completion facility that is comparable to shells like
28 ;; Completions are context-sensitive, which means that pressing <TAB>
29 ;; after the command 'rmdir' will result in a list of directories,
30 ;; while doing so after 'rm' will result in a list of all file
33 ;; Many builtin completion rules are provided, for commands such as
34 ;; `cvs', or RedHat's `rpm' utility. Adding new completion rules is
35 ;; no more difficult than writing a plain Lisp functions, and they can
36 ;; be debugged, profiled, and compiled using exactly the same
37 ;; facilities (since in fact, they *are* just Lisp functions). See
38 ;; the definition of the function `pcomplete/make' for an example of
39 ;; how to write a completion function.
41 ;; The completion facility is very easy to use. Just press TAB. If
42 ;; there are a large number of possible completions, a buffer will
43 ;; appear showing a list of them. Completions may be selected from
44 ;; that buffer using the mouse. If no completion is selected, and the
45 ;; user starts doing something else, the display buffer will
46 ;; automatically disappear.
48 ;; If the list of possible completions is very small, Eshell will
49 ;; "cycle" through them, selecting a different entry each time <TAB>
50 ;; is pressed. <S-TAB> may be used to cycle in the opposite
53 ;; Glob patterns can also be cycled. For example, entering 'echo
54 ;; x*<tab>' will cycle through all the filenames beginning with 'x'.
55 ;; This is done because the glob list is treated as though it were a
56 ;; list of possible completions. Pressing <C-c SPC> will insert all
57 ;; of the matching glob patterns at point.
59 ;; If a Lisp form is being entered, <TAB> will complete the Lisp
60 ;; symbol name, in exactly the same way that <M-TAB> does in Emacs
63 ;; The list of possible completions can be viewed at any point by
66 ;; Finally, context-related help can be accessed by pressing <C-c i>.
67 ;; This only works well if the completion function has provided Eshell
68 ;; with sufficient pointers to locate the relevant help text.
78 (eshell-defgroup eshell-cmpl nil
79 "This module provides a programmable completion function bound to
80 the TAB key, which allows for completing command names, file names,
81 variable names, arguments, etc."
82 :tag "Argument completion"
83 :group 'eshell-module)
87 (defcustom eshell-cmpl-load-hook '(eshell-cmpl-initialize)
88 "A list of functions to run when `eshell-cmpl' is loaded."
92 (defcustom eshell-show-lisp-completions nil
93 "If non-nil, include Lisp functions in the command completion list.
94 If this variable is nil, Lisp completion can still be done in command
95 position by using M-TAB instead of TAB."
99 (defcustom eshell-show-lisp-alternatives t
100 "If non-nil, and no other completions found, show Lisp functions.
101 Setting this variable means nothing if `eshell-show-lisp-completions'
106 (defcustom eshell-no-completion-during-jobs t
107 "If non-nil, don't allow completion while a process is running."
111 (defcustom eshell-command-completions-alist
112 '(("acroread" . "\\.pdf\\'")
113 ("xpdf" . "\\.pdf\\'")
114 ("ar" . "\\.[ao]\\'")
115 ("gcc" . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
116 ("g++" . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
117 ("cc" . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
118 ("CC" . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
119 ("acc" . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
120 ("bcc" . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
121 ("readelf" . "\\(\\`[^.]*\\|\\.\\([ao]\\|so\\)\\)\\'")
122 ("objdump" . "\\(\\`[^.]*\\|\\.\\([ao]\\|so\\)\\)\\'")
123 ("nm" . "\\(\\`[^.]*\\|\\.\\([ao]\\|so\\)\\)\\'")
124 ("gdb" . "\\`\\([^.]*\\|a\\.out\\)\\'")
125 ("dbx" . "\\`\\([^.]*\\|a\\.out\\)\\'")
126 ("sdb" . "\\`\\([^.]*\\|a\\.out\\)\\'")
127 ("adb" . "\\`\\([^.]*\\|a\\.out\\)\\'"))
128 "An alist that defines simple argument type correlations.
129 This is provided for common commands, as a simplistic alternative
130 to writing a completion function."
131 :type '(repeat (cons string regexp))
134 (defcustom eshell-cmpl-file-ignore "~\\'"
135 (documentation-property 'pcomplete-file-ignore
136 'variable-documentation)
137 :type (get 'pcomplete-file-ignore 'custom-type)
140 (defcustom eshell-cmpl-dir-ignore "\\`\\(\\.\\.?\\|CVS\\)/\\'"
141 (documentation-property 'pcomplete-dir-ignore
142 'variable-documentation)
143 :type (get 'pcomplete-dir-ignore 'custom-type)
146 (defcustom eshell-cmpl-ignore-case (eshell-under-windows-p)
147 (documentation-property 'pcomplete-ignore-case
148 'variable-documentation)
149 :type (get 'pcomplete-ignore-case 'custom-type)
152 (defcustom eshell-cmpl-autolist nil
153 (documentation-property 'pcomplete-autolist
154 'variable-documentation)
155 :type (get 'pcomplete-autolist 'custom-type)
158 (defcustom eshell-cmpl-suffix-list (list ?/ ?:)
159 (documentation-property 'pcomplete-suffix-list
160 'variable-documentation)
161 :type (get 'pcomplete-suffix-list 'custom-type)
164 (defcustom eshell-cmpl-recexact nil
165 (documentation-property 'pcomplete-recexact
166 'variable-documentation)
167 :type (get 'pcomplete-recexact 'custom-type)
170 (defcustom eshell-cmpl-man-function 'man
171 (documentation-property 'pcomplete-man-function
172 'variable-documentation)
173 :type (get 'pcomplete-man-function 'custom-type)
176 (defcustom eshell-cmpl-compare-entry-function 'file-newer-than-file-p
177 (documentation-property 'pcomplete-compare-entry-function
178 'variable-documentation)
179 :type (get 'pcomplete-compare-entry-function 'custom-type)
182 (defcustom eshell-cmpl-expand-before-complete nil
183 (documentation-property 'pcomplete-expand-before-complete
184 'variable-documentation)
185 :type (get 'pcomplete-expand-before-complete 'custom-type)
188 (defcustom eshell-cmpl-cycle-completions t
189 (documentation-property 'pcomplete-cycle-completions
190 'variable-documentation)
191 :type (get 'pcomplete-cycle-completions 'custom-type)
194 (defcustom eshell-cmpl-cycle-cutoff-length 5
195 (documentation-property 'pcomplete-cycle-cutoff-length
196 'variable-documentation)
197 :type (get 'pcomplete-cycle-cutoff-length 'custom-type)
200 (defcustom eshell-cmpl-restore-window-delay 1
201 (documentation-property 'pcomplete-restore-window-delay
202 'variable-documentation)
203 :type (get 'pcomplete-restore-window-delay 'custom-type)
206 (defcustom eshell-command-completion-function
209 (pcomplete-here (eshell-complete-commands-list))))
210 (documentation-property 'pcomplete-command-completion-function
211 'variable-documentation)
212 :type (get 'pcomplete-command-completion-function 'custom-type)
215 (defcustom eshell-cmpl-command-name-function
216 'eshell-completion-command-name
217 (documentation-property 'pcomplete-command-name-function
218 'variable-documentation)
219 :type (get 'pcomplete-command-name-function 'custom-type)
222 (defcustom eshell-default-completion-function
225 (while (pcomplete-here
226 (pcomplete-dirs-or-entries
227 (cdr (assoc (funcall eshell-cmpl-command-name-function)
228 eshell-command-completions-alist)))))))
229 (documentation-property 'pcomplete-default-completion-function
230 'variable-documentation)
231 :type (get 'pcomplete-default-completion-function 'custom-type)
234 (defcustom eshell-cmpl-use-paring t
235 (documentation-property 'pcomplete-use-paring 'variable-documentation)
236 :type (get 'pcomplete-use-paring 'custom-type)
241 (defun eshell-cmpl-initialize ()
242 "Initialize the completions module."
243 (unless (fboundp 'pcomplete)
244 (load "pcmpl-auto" t t))
245 (set (make-local-variable 'pcomplete-command-completion-function)
246 eshell-command-completion-function)
247 (set (make-local-variable 'pcomplete-command-name-function)
248 eshell-cmpl-command-name-function)
249 (set (make-local-variable 'pcomplete-default-completion-function)
250 eshell-default-completion-function)
251 (set (make-local-variable 'pcomplete-parse-arguments-function)
252 'eshell-complete-parse-arguments)
253 (set (make-local-variable 'pcomplete-file-ignore)
254 eshell-cmpl-file-ignore)
255 (set (make-local-variable 'pcomplete-dir-ignore)
256 eshell-cmpl-dir-ignore)
257 (set (make-local-variable 'pcomplete-ignore-case)
258 eshell-cmpl-ignore-case)
259 (set (make-local-variable 'pcomplete-autolist)
260 eshell-cmpl-autolist)
261 (set (make-local-variable 'pcomplete-suffix-list)
262 eshell-cmpl-suffix-list)
263 (set (make-local-variable 'pcomplete-recexact)
264 eshell-cmpl-recexact)
265 (set (make-local-variable 'pcomplete-man-function)
266 eshell-cmpl-man-function)
267 (set (make-local-variable 'pcomplete-compare-entry-function)
268 eshell-cmpl-compare-entry-function)
269 (set (make-local-variable 'pcomplete-expand-before-complete)
270 eshell-cmpl-expand-before-complete)
271 (set (make-local-variable 'pcomplete-cycle-completions)
272 eshell-cmpl-cycle-completions)
273 (set (make-local-variable 'pcomplete-cycle-cutoff-length)
274 eshell-cmpl-cycle-cutoff-length)
275 (set (make-local-variable 'pcomplete-restore-window-delay)
276 eshell-cmpl-restore-window-delay)
277 (set (make-local-variable 'pcomplete-use-paring)
278 eshell-cmpl-use-paring)
279 ;; `pcomplete-arg-quote-list' should only be set after all the
280 ;; load-hooks for any other extension modules have been run, which
281 ;; is true at the time `eshell-mode-hook' is run
282 (add-hook 'eshell-mode-hook
285 (set (make-local-variable 'pcomplete-arg-quote-list)
286 eshell-special-chars-outside-quoting))) nil t)
287 (add-hook 'pcomplete-quote-arg-hook 'eshell-quote-backslash nil t)
288 (define-key eshell-mode-map [(meta tab)] 'lisp-complete-symbol)
289 (define-key eshell-mode-map [(meta control ?i)] 'lisp-complete-symbol)
290 (define-key eshell-command-map [(meta ?h)] 'eshell-completion-help)
291 (define-key eshell-command-map [tab] 'pcomplete-expand-and-complete)
292 (define-key eshell-command-map [(control ?i)]
293 'pcomplete-expand-and-complete)
294 (define-key eshell-command-map [space] 'pcomplete-expand)
295 (define-key eshell-command-map [? ] 'pcomplete-expand)
296 (define-key eshell-mode-map [tab] 'pcomplete)
297 (define-key eshell-mode-map [(control ?i)] 'pcomplete)
298 ;; jww (1999-10-19): Will this work on anything but X?
299 (if (featurep 'xemacs)
300 (define-key eshell-mode-map [iso-left-tab] 'pcomplete-reverse)
301 (define-key eshell-mode-map [(shift iso-lefttab)] 'pcomplete-reverse)
302 (define-key eshell-mode-map [(shift control ?i)] 'pcomplete-reverse))
303 (define-key eshell-mode-map [(meta ??)] 'pcomplete-list))
305 (defun eshell-completion-command-name ()
306 "Return the command name, possibly sans globbing."
307 (let ((cmd (file-name-nondirectory (pcomplete-arg 'first))))
308 (setq cmd (if (and (> (length cmd) 0)
309 (eq (aref cmd 0) eshell-explicit-command-char))
312 (if (eshell-under-windows-p)
313 (file-name-sans-extension cmd)
316 (defun eshell-completion-help ()
318 (if (= (point) eshell-last-output-end)
319 (describe-prefix-bindings)
320 (call-interactively 'pcomplete-help)))
322 (defun eshell-complete-parse-arguments ()
323 "Parse the command line arguments for `pcomplete-argument'."
324 (when (and eshell-no-completion-during-jobs
325 (eshell-interactive-process))
326 (insert-and-inherit "\t")
327 (throw 'pcompleted t))
328 (let ((end (point-marker))
329 (begin (save-excursion (eshell-bol) (point)))
332 (when (memq this-command '(pcomplete-expand
333 pcomplete-expand-and-complete))
334 (run-hook-with-args 'eshell-expand-input-functions begin end)
337 (setq end (point-marker)))
339 (catch 'eshell-incomplete
341 (setq args (eshell-parse-arguments begin end)))))
342 (cond ((memq (car delim) '(?\{ ?\<))
343 (setq begin (1+ (cadr delim))
344 args (eshell-parse-arguments begin end)))
345 ((eq (car delim) ?\()
346 (lisp-complete-symbol)
347 (throw 'pcompleted t))
349 (insert-and-inherit "\t")
350 (throw 'pcompleted t))))
351 (when (get-text-property (1- end) 'comment)
352 (insert-and-inherit "\t")
353 (throw 'pcompleted t))
356 (if (get-text-property pos 'arg-begin)
357 (nconc posns (list pos)))
358 (setq pos (1+ pos))))
359 (setq posns (cdr posns))
360 (assert (= (length args) (length posns)))
365 (if (and (consp (car a))
366 (eq (caar a) 'eshell-operator))
368 (setq a (cdr a) i (1+ i)))
370 (setq args (nthcdr (1+ l) args)
371 posns (nthcdr (1+ l) posns))))
372 (assert (= (length args) (length posns)))
373 (when (and args (eq (char-syntax (char-before end)) ? )
374 (not (eq (char-before (1- end)) ?\\)))
375 (nconc args (list ""))
376 (nconc posns (list (point))))
384 (list 'eshell-commands arg) t)))
385 (assert (eq (car result) 'quote))
389 (setq val (number-to-string val)))
394 (defun eshell-complete-commands-list ()
395 "Generate list of applicable, visible commands."
396 (let ((filename (pcomplete-arg)) glob-name)
397 (if (file-name-directory filename)
398 (pcomplete-executables)
399 (if (and (> (length filename) 0)
400 (eq (aref filename 0) eshell-explicit-command-char))
401 (setq filename (substring filename 1)
402 pcomplete-stub filename
404 (let* ((paths (eshell-parse-colon-path eshell-path-env))
405 (cwd (file-name-as-directory
406 (expand-file-name default-directory)))
407 (path "") (comps-in-path ())
408 (file "") (filepath "") (completions ()))
409 ;; Go thru each path in the search path, finding completions.
411 (setq path (file-name-as-directory
412 (expand-file-name (or (car paths) ".")))
414 (and (file-accessible-directory-p path)
415 (file-name-all-completions filename path)))
416 ;; Go thru each completion found, to see whether it should
419 (setq file (car comps-in-path)
420 filepath (concat path file))
421 (if (and (not (member file completions)) ;
422 (or (string-equal path cwd)
423 (not (file-directory-p filepath)))
424 (file-executable-p filepath))
425 (setq completions (cons file completions)))
426 (setq comps-in-path (cdr comps-in-path)))
427 (setq paths (cdr paths)))
428 ;; Add aliases which are currently visible, and Lisp functions.
429 (pcomplete-uniqify-list
433 (append (and (eshell-using-module 'eshell-alias)
434 (funcall (symbol-function 'eshell-alias-completions)
441 (all-completions (concat "eshell/" filename)
443 nil '(eshell-find-alias-function))
445 (append (and (or eshell-show-lisp-completions
446 (and eshell-show-lisp-alternatives
448 (all-completions filename obarray 'functionp))
454 ;; generated-autoload-file: "esh-groups.el"
457 ;;; em-cmpl.el ends here