1 ;;; em-cmpl.el --- completion using the TAB key -*- lexical-binding:t -*-
3 ;; Copyright (C) 1999-2018 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 <https://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 M-h>.
67 ;; This only works well if the completion function has provided Eshell
68 ;; with sufficient pointers to locate the relevant help text.
82 (defgroup eshell-cmpl nil
83 "This module provides a programmable completion function bound to
84 the TAB key, which allows for completing command names, file names,
85 variable names, arguments, etc."
86 :tag
"Argument completion"
87 :group
'eshell-module
))
91 (defcustom eshell-cmpl-load-hook nil
92 "A list of functions to run when `eshell-cmpl' is loaded."
93 :version
"24.1" ; removed eshell-cmpl-initialize
97 (defcustom eshell-show-lisp-completions nil
98 "If non-nil, include Lisp functions in the command completion list.
99 If this variable is nil, Lisp completion can still be done in command
100 position by using M-TAB instead of TAB."
104 (defcustom eshell-show-lisp-alternatives t
105 "If non-nil, and no other completions found, show Lisp functions.
106 Setting this variable means nothing if `eshell-show-lisp-completions'
111 (defcustom eshell-no-completion-during-jobs t
112 "If non-nil, don't allow completion while a process is running."
116 (defcustom eshell-command-completions-alist
117 '(("acroread" .
"\\.pdf\\'")
118 ("xpdf" .
"\\.pdf\\'")
119 ("ar" .
"\\.[ao]\\'")
120 ("gcc" .
"\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
121 ("g++" .
"\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
122 ("cc" .
"\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
123 ("CC" .
"\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
124 ("acc" .
"\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
125 ("bcc" .
"\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
126 ("readelf" .
"\\(\\`[^.]*\\|\\.\\([ao]\\|so\\)\\)\\'")
127 ("objdump" .
"\\(\\`[^.]*\\|\\.\\([ao]\\|so\\)\\)\\'")
128 ("nm" .
"\\(\\`[^.]*\\|\\.\\([ao]\\|so\\)\\)\\'")
129 ("gdb" .
"\\`\\([^.]*\\|a\\.out\\)\\'")
130 ("dbx" .
"\\`\\([^.]*\\|a\\.out\\)\\'")
131 ("sdb" .
"\\`\\([^.]*\\|a\\.out\\)\\'")
132 ("adb" .
"\\`\\([^.]*\\|a\\.out\\)\\'"))
133 "An alist that defines simple argument type correlations.
134 This is provided for common commands, as a simplistic alternative
135 to writing a completion function."
136 :type
'(repeat (cons string regexp
))
139 (defun eshell-cmpl--custom-variable-docstring (pcomplete-var)
140 "Generate the docstring of a variable derived from a pcomplete-* variable."
141 (format "%s\n\nIts value is assigned to `%s' locally after eshell starts."
142 (documentation-property pcomplete-var
143 'variable-documentation t
)
144 (symbol-name pcomplete-var
)))
146 (defcustom eshell-cmpl-file-ignore
"~\\'"
147 (eshell-cmpl--custom-variable-docstring 'pcomplete-file-ignore
)
148 :type
(get 'pcomplete-file-ignore
'custom-type
)
151 (defcustom eshell-cmpl-dir-ignore
"\\`\\(\\.\\.?\\|CVS\\)/\\'"
152 (eshell-cmpl--custom-variable-docstring 'pcomplete-dir-ignore
)
153 :type
(get 'pcomplete-dir-ignore
'custom-type
)
156 (defcustom eshell-cmpl-ignore-case
(eshell-under-windows-p)
157 (eshell-cmpl--custom-variable-docstring 'pcomplete-ignore-case
)
158 :type
(get 'pcomplete-ignore-case
'custom-type
)
161 (defcustom eshell-cmpl-autolist nil
162 (eshell-cmpl--custom-variable-docstring 'pcomplete-autolist
)
163 :type
(get 'pcomplete-autolist
'custom-type
)
166 (defcustom eshell-cmpl-suffix-list
(list ?
/ ?
:)
167 (eshell-cmpl--custom-variable-docstring 'pcomplete-suffix-list
)
168 :type
(get 'pcomplete-suffix-list
'custom-type
)
171 (defcustom eshell-cmpl-recexact nil
172 (eshell-cmpl--custom-variable-docstring 'pcomplete-recexact
)
173 :type
(get 'pcomplete-recexact
'custom-type
)
176 (defcustom eshell-cmpl-man-function
'man
177 (eshell-cmpl--custom-variable-docstring 'pcomplete-man-function
)
178 :type
(get 'pcomplete-man-function
'custom-type
)
181 (defcustom eshell-cmpl-compare-entry-function
'file-newer-than-file-p
182 (eshell-cmpl--custom-variable-docstring 'pcomplete-compare-entry-function
)
183 :type
(get 'pcomplete-compare-entry-function
'custom-type
)
186 (defcustom eshell-cmpl-expand-before-complete nil
187 (eshell-cmpl--custom-variable-docstring 'pcomplete-expand-before-complete
)
188 :type
(get 'pcomplete-expand-before-complete
'custom-type
)
191 (defcustom eshell-cmpl-cycle-completions t
192 (eshell-cmpl--custom-variable-docstring 'pcomplete-cycle-completions
)
193 :type
(get 'pcomplete-cycle-completions
'custom-type
)
196 (defcustom eshell-cmpl-cycle-cutoff-length
5
197 (eshell-cmpl--custom-variable-docstring 'pcomplete-cycle-cutoff-length
)
198 :type
(get 'pcomplete-cycle-cutoff-length
'custom-type
)
201 (defcustom eshell-cmpl-restore-window-delay
1
202 (eshell-cmpl--custom-variable-docstring 'pcomplete-restore-window-delay
)
203 :type
(get 'pcomplete-restore-window-delay
'custom-type
)
206 (defcustom eshell-command-completion-function
209 (pcomplete-here (eshell-complete-commands-list))))
210 (eshell-cmpl--custom-variable-docstring 'pcomplete-command-completion-function
)
211 :type
(get 'pcomplete-command-completion-function
'custom-type
)
214 (defcustom eshell-cmpl-command-name-function
215 'eshell-completion-command-name
216 (eshell-cmpl--custom-variable-docstring 'pcomplete-command-name-function
)
217 :type
(get 'pcomplete-command-name-function
'custom-type
)
220 (defcustom eshell-default-completion-function
223 (while (pcomplete-here
224 (pcomplete-dirs-or-entries
225 (cdr (assoc (funcall eshell-cmpl-command-name-function
)
226 eshell-command-completions-alist
)))))))
227 (eshell-cmpl--custom-variable-docstring 'pcomplete-default-completion-function
)
228 :type
(get 'pcomplete-default-completion-function
'custom-type
)
231 (defcustom eshell-cmpl-use-paring t
232 (eshell-cmpl--custom-variable-docstring 'pcomplete-use-paring
)
233 :type
(get 'pcomplete-use-paring
'custom-type
)
238 (defun eshell-complete-lisp-symbol ()
239 "Try to complete the text around point as a Lisp symbol."
241 (let ((completion-at-point-functions '(lisp-completion-at-point)))
242 (completion-at-point)))
244 (defun eshell-cmpl-initialize ()
245 "Initialize the completions module."
246 (set (make-local-variable 'pcomplete-command-completion-function
)
247 eshell-command-completion-function
)
248 (set (make-local-variable 'pcomplete-command-name-function
)
249 eshell-cmpl-command-name-function
)
250 (set (make-local-variable 'pcomplete-default-completion-function
)
251 eshell-default-completion-function
)
252 (set (make-local-variable 'pcomplete-parse-arguments-function
)
253 'eshell-complete-parse-arguments
)
254 (set (make-local-variable 'pcomplete-file-ignore
)
255 eshell-cmpl-file-ignore
)
256 (set (make-local-variable 'pcomplete-dir-ignore
)
257 eshell-cmpl-dir-ignore
)
258 (set (make-local-variable 'pcomplete-ignore-case
)
259 eshell-cmpl-ignore-case
)
260 (set (make-local-variable 'pcomplete-autolist
)
261 eshell-cmpl-autolist
)
262 (set (make-local-variable 'pcomplete-suffix-list
)
263 eshell-cmpl-suffix-list
)
264 (set (make-local-variable 'pcomplete-recexact
)
265 eshell-cmpl-recexact
)
266 (set (make-local-variable 'pcomplete-man-function
)
267 eshell-cmpl-man-function
)
268 (set (make-local-variable 'pcomplete-compare-entry-function
)
269 eshell-cmpl-compare-entry-function
)
270 (set (make-local-variable 'pcomplete-expand-before-complete
)
271 eshell-cmpl-expand-before-complete
)
272 (set (make-local-variable 'pcomplete-cycle-completions
)
273 eshell-cmpl-cycle-completions
)
274 (set (make-local-variable 'pcomplete-cycle-cutoff-length
)
275 eshell-cmpl-cycle-cutoff-length
)
276 (set (make-local-variable 'pcomplete-restore-window-delay
)
277 eshell-cmpl-restore-window-delay
)
278 (set (make-local-variable 'pcomplete-use-paring
)
279 eshell-cmpl-use-paring
)
280 ;; `comint-file-name-quote-list' should only be set after all the
281 ;; load-hooks for any other extension modules have been run, which
282 ;; is true at the time `eshell-mode-hook' is run
283 (add-hook 'eshell-mode-hook
286 (set (make-local-variable 'comint-file-name-quote-list
)
287 eshell-special-chars-outside-quoting
))) nil t
)
288 (add-hook 'pcomplete-quote-arg-hook
'eshell-quote-backslash nil t
)
289 (define-key eshell-mode-map
[(meta tab
)] 'eshell-complete-lisp-symbol
)
290 (define-key eshell-mode-map
[(meta control ?i
)] 'eshell-complete-lisp-symbol
)
291 (define-key eshell-command-map
[(meta ?h
)] 'eshell-completion-help
)
292 (define-key eshell-command-map
[tab] 'pcomplete-expand-and-complete)
293 (define-key eshell-command-map [(control ?i)]
294 'pcomplete-expand-and-complete)
295 (define-key eshell-command-map [space] 'pcomplete-expand)
296 (define-key eshell-command-map [? ] 'pcomplete-expand)
297 (define-key eshell-mode-map [tab] 'eshell-pcomplete
)
298 (define-key eshell-mode-map
[(control ?i
)] 'eshell-pcomplete
)
299 (add-hook 'completion-at-point-functions
300 #'pcomplete-completions-at-point nil t
)
301 ;; jww (1999-10-19): Will this work on anything but X?
302 (if (featurep 'xemacs
)
303 (define-key eshell-mode-map
[iso-left-tab
] 'pcomplete-reverse
)
304 (define-key eshell-mode-map
[backtab] 'pcomplete-reverse))
305 (define-key eshell-mode-map [(meta ??)] 'pcomplete-list))
307 (defun eshell-completion-command-name ()
308 "Return the command name, possibly sans globbing."
309 (let ((cmd (file-name-nondirectory (pcomplete-arg 'first))))
310 (setq cmd (if (and (> (length cmd) 0)
311 (eq (aref cmd 0) eshell-explicit-command-char))
314 (if (eshell-under-windows-p)
315 (file-name-sans-extension cmd)
318 (defun eshell-completion-help ()
320 (if (= (point) eshell-last-output-end)
321 (describe-prefix-bindings)
322 (call-interactively 'pcomplete-help)))
324 (defun eshell-complete-parse-arguments ()
325 "Parse the command line arguments for `pcomplete-argument'."
326 (when (and eshell-no-completion-during-jobs
327 (eshell-interactive-process))
328 (insert-and-inherit "\t")
329 (throw 'pcompleted t))
330 (let ((end (point-marker))
331 (begin (save-excursion (eshell-bol) (point)))
334 (when (memq this-command '(pcomplete-expand
335 pcomplete-expand-and-complete))
336 (run-hook-with-args 'eshell-expand-input-functions begin end)
339 (setq end (point-marker)))
341 (catch 'eshell-incomplete
343 (setq args (eshell-parse-arguments begin end)))))
344 (cond ((memq (car delim) '(?\{ ?\<))
345 (setq begin (1+ (cadr delim))
346 args (eshell-parse-arguments begin end)))
347 ((eq (car delim) ?\()
348 (eshell-complete-lisp-symbol)
349 (throw 'pcompleted t))
351 (insert-and-inherit "\t")
352 (throw 'pcompleted t))))
353 (when (get-text-property (1- end) 'comment)
354 (insert-and-inherit "\t")
355 (throw 'pcompleted t))
358 (if (get-text-property pos 'arg-begin)
359 (nconc posns (list pos)))
360 (setq pos (1+ pos))))
361 (setq posns (cdr posns))
362 (cl-assert (= (length args) (length posns)))
367 (if (and (consp (car a))
368 (eq (caar a) 'eshell-operator))
370 (setq a (cdr a) i (1+ i)))
372 (setq args (nthcdr (1+ l) args)
373 posns (nthcdr (1+ l) posns))))
374 (cl-assert (= (length args) (length posns)))
375 (when (and args (eq (char-syntax (char-before end)) ? )
376 (not (eq (char-before (1- end)) ?\\)))
377 (nconc args (list ""))
378 (nconc posns (list (point))))
386 (list 'eshell-commands arg) t)))
387 (cl-assert (eq (car result) 'quote))
391 (setq val (number-to-string val)))
396 (defun eshell-complete-commands-list ()
397 "Generate list of applicable, visible commands."
398 (let ((filename (pcomplete-arg)) glob-name)
399 (if (file-name-directory filename)
400 (if eshell-force-execution
401 (pcomplete-dirs-or-entries nil 'file-readable-p)
402 (pcomplete-executables))
403 (if (and (> (length filename) 0)
404 (eq (aref filename 0) eshell-explicit-command-char))
405 (setq filename (substring filename 1)
406 pcomplete-stub filename
408 (let* ((paths (eshell-parse-colon-path eshell-path-env))
409 (cwd (file-name-as-directory
410 (expand-file-name default-directory)))
411 (path "") (comps-in-path ())
412 (file "") (filepath "") (completions ()))
413 (if (eshell-under-windows-p)
415 ;; Go thru each path in the search path, finding completions.
417 (setq path (file-name-as-directory
418 (expand-file-name (or (car paths) ".")))
420 (and (file-accessible-directory-p path)
421 (file-name-all-completions filename path)))
422 ;; Go thru each completion found, to see whether it should
425 (setq file (car comps-in-path)
426 filepath (concat path file))
427 (if (and (not (member file completions)) ;
428 (or (string-equal path cwd)
429 (not (file-directory-p filepath)))
430 (if eshell-force-execution
431 (file-readable-p filepath)
432 (file-executable-p filepath)))
433 (setq completions (cons file completions)))
434 (setq comps-in-path (cdr comps-in-path)))
435 (setq paths (cdr paths)))
436 ;; Add aliases which are currently visible, and Lisp functions.
437 (pcomplete-uniqify-list
441 (append (and (eshell-using-module 'eshell-alias)
442 (funcall (symbol-function 'eshell-alias-completions)
449 (all-completions (concat "eshell/" filename)
451 nil '(eshell-find-alias-function))
453 (append (and (or eshell-show-lisp-completions
454 (and eshell-show-lisp-alternatives
456 (all-completions filename obarray 'functionp))
459 (defun eshell-pcomplete (&optional interactively)
460 "Eshell wrapper for `pcomplete'."
462 ;; Pretend to be pcomplete so that cycling works (bug#13293).
463 (setq this-command 'pcomplete)
466 (call-interactively 'pcomplete)
468 (text-read-only (completion-at-point)))) ; Workaround for bug#12838.
473 ;; generated-autoload-file: "esh-groups.el"
476 ;;; em-cmpl.el ends here