1
0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-12-02 08:22:22 +00:00
emacs/lisp/eshell/em-cmpl.el
Jim Porter 4c924a5333 Use 'esh-module-autoload' for Eshell modules' defgroups
This will let modules define their own, regular autoloads, independent
of the core Eshell machinery for defining modules.

* lisp/eshell/em-alias.el (em-alias):
* lisp/eshell/em-banner.el (em-banner):
* lisp/eshell/em-basic.el (em-basic):
* lisp/eshell/em-cmpl.el (em-cmpl):
* lisp/eshell/em-dirs.el (em-dirs):
* lisp/eshell/em-elecslash.el (em-elecslash):
* lisp/eshell/em-extpipe.el:
* lisp/eshell/em-glob.el (em-glob):
* lisp/eshell/em-hist.el (em-hist):
* lisp/eshell/em-ls.el (em-ls):
* lisp/eshell/em-pred.el (em-pred):
* lisp/eshell/em-prompt.el (em-prompt):
* lisp/eshell/em-rebind.el (em-rebind):
* lisp/eshell/em-script.el (em-script):
* lisp/eshell/em-smart.el (em-smart):
* lisp/eshell/em-term.el (em-term):
* lisp/eshell/em-tramp.el (em-tramp):
* lisp/eshell/em-unix.el (em-unix):
* lisp/eshell/em-xtra.el (em-xtra): Use 'esh-module-autoload'.

* lisp/eshell/esh-module.el ("esh-module-loaddefs"): Load this instead
of "esh-groups".

* .gitignore: Change esh-groups.el to esh-module-loaddefs.el
2024-05-29 12:09:05 -07:00

522 lines
21 KiB
EmacsLisp

;;; em-cmpl.el --- completion using the TAB key -*- lexical-binding:t -*-
;; Copyright (C) 1999-2024 Free Software Foundation, Inc.
;; Author: John Wiegley <johnw@gnu.org>
;; This file is part of GNU Emacs.
;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; Eshell, by using the pcomplete package, provides a full
;; programmable completion facility that is comparable to shells like
;; tcsh or zsh.
;;
;; Completions are context-sensitive, which means that pressing <TAB>
;; after the command 'rmdir' will result in a list of directories,
;; while doing so after 'rm' will result in a list of all file
;; entries.
;;
;; Many builtin completion rules are provided, for commands such as
;; `cvs', or RedHat's `rpm' utility. Adding new completion rules is
;; no more difficult than writing a plain Lisp functions, and they can
;; be debugged, profiled, and compiled using exactly the same
;; facilities (since in fact, they *are* just Lisp functions). See
;; the definition of the function `pcomplete/make' for an example of
;; how to write a completion function.
;;
;; The completion facility is very easy to use. Just press TAB. If
;; there are a large number of possible completions, a buffer will
;; appear showing a list of them. Completions may be selected from
;; that buffer using the mouse. If no completion is selected, and the
;; user starts doing something else, the display buffer will
;; automatically disappear.
;;
;; If the list of possible completions is very small, Eshell will
;; "cycle" through them, selecting a different entry each time <TAB>
;; is pressed. <S-TAB> may be used to cycle in the opposite
;; direction.
;;
;; Glob patterns can also be cycled. For example, entering 'echo
;; x*<tab>' will cycle through all the filenames beginning with 'x'.
;; This is done because the glob list is treated as though it were a
;; list of possible completions. Pressing <C-c SPC> will insert all
;; of the matching glob patterns at point.
;;
;; If a Lisp form is being entered, <TAB> will complete the Lisp
;; symbol name, in exactly the same way that <M-TAB> does in Emacs
;; Lisp mode.
;;
;; The list of possible completions can be viewed at any point by
;; pressing <M-?>.
;;
;; Finally, context-related help can be accessed by pressing <C-c M-h>.
;; This only works well if the completion function has provided Eshell
;; with sufficient pointers to locate the relevant help text.
;;; Code:
(require 'pcomplete)
(require 'esh-mode)
(require 'esh-util)
(require 'em-dirs)
(eval-when-compile (require 'cl-lib))
;;;###esh-module-autoload
(progn
(defgroup eshell-cmpl nil
"This module provides a programmable completion function bound to
the TAB key, which allows for completing command names, file names,
variable names, arguments, etc."
:tag "Argument completion"
:group 'eshell-module))
;;; User Variables:
(defcustom eshell-cmpl-load-hook nil
"A list of functions to run when `eshell-cmpl' is loaded."
:version "24.1" ; removed eshell-cmpl-initialize
:type 'hook)
(defcustom eshell-show-lisp-completions nil
"If non-nil, include Lisp functions in the command completion list.
If this variable is nil, Lisp completion can still be done in command
position by using M-TAB instead of TAB."
:type 'boolean)
(defcustom eshell-show-lisp-alternatives t
"If non-nil, and no other completions found, show Lisp functions.
Setting this variable means nothing if `eshell-show-lisp-completions'
is non-nil."
:type 'boolean)
(defcustom eshell-no-completion-during-jobs t
"If non-nil, don't allow completion while a process is running."
:type 'boolean)
(defcustom eshell-command-completions-alist
'(("acroread" . "\\.pdf\\'")
("xpdf" . "\\.pdf\\'")
("gunzip" . "\\.t?gz\\'")
("bunzip2" . "\\.t?bz2\\'")
("unxz" . "\\.t?xz\\'")
("ar" . "\\.[ao]\\'")
("gcc" . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
("g++" . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
("cc" . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
("CC" . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
("acc" . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
("bcc" . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
("readelf" . "\\(\\`[^.]*\\|\\.\\([ao]\\|so\\)\\)\\'")
("objdump" . "\\(\\`[^.]*\\|\\.\\([ao]\\|so\\)\\)\\'")
("nm" . "\\(\\`[^.]*\\|\\.\\([ao]\\|so\\)\\)\\'")
("gdb" . "\\`\\([^.]*\\|a\\.out\\)\\'")
("dbx" . "\\`\\([^.]*\\|a\\.out\\)\\'")
("sdb" . "\\`\\([^.]*\\|a\\.out\\)\\'")
("adb" . "\\`\\([^.]*\\|a\\.out\\)\\'"))
"An alist that defines simple argument type correlations.
This is provided for common commands, as a simplistic alternative
to writing a completion function."
:type '(repeat (cons string regexp)))
(defun eshell-cmpl--custom-variable-docstring (pcomplete-var)
"Generate the docstring of a variable derived from a pcomplete-* variable."
(format "%s\n\nIts value is assigned to `%s' locally after eshell starts."
(documentation-property pcomplete-var
'variable-documentation t)
(symbol-name pcomplete-var)))
(defcustom eshell-cmpl-file-ignore "~\\'"
(eshell-cmpl--custom-variable-docstring 'pcomplete-file-ignore)
:type (get 'pcomplete-file-ignore 'custom-type))
(defcustom eshell-cmpl-dir-ignore "\\`\\(\\.\\.?\\|CVS\\)/\\'"
(eshell-cmpl--custom-variable-docstring 'pcomplete-dir-ignore)
:type (get 'pcomplete-dir-ignore 'custom-type))
(defcustom eshell-cmpl-remote-file-ignore nil
(eshell-cmpl--custom-variable-docstring 'pcomplete-remote-file-ignore)
:type (get 'pcomplete-remote-file-ignore 'custom-type))
(defcustom eshell-cmpl-ignore-case (eshell-under-windows-p)
(eshell-cmpl--custom-variable-docstring 'completion-ignore-case)
:type (get 'completion-ignore-case 'custom-type))
(defcustom eshell-cmpl-autolist nil
(eshell-cmpl--custom-variable-docstring 'pcomplete-autolist)
:type (get 'pcomplete-autolist 'custom-type))
(defcustom eshell-cmpl-recexact nil
(eshell-cmpl--custom-variable-docstring 'pcomplete-recexact)
:type (get 'pcomplete-recexact 'custom-type))
(defcustom eshell-cmpl-man-function #'man
(eshell-cmpl--custom-variable-docstring 'pcomplete-man-function)
:type (get 'pcomplete-man-function 'custom-type))
(defcustom eshell-cmpl-compare-entry-function #'file-newer-than-file-p
(eshell-cmpl--custom-variable-docstring 'pcomplete-compare-entry-function)
:type (get 'pcomplete-compare-entry-function 'custom-type))
(defcustom eshell-cmpl-expand-before-complete nil
(eshell-cmpl--custom-variable-docstring 'pcomplete-expand-before-complete)
:type (get 'pcomplete-expand-before-complete 'custom-type))
(defcustom eshell-cmpl-cycle-completions t
(eshell-cmpl--custom-variable-docstring 'pcomplete-cycle-completions)
:type (get 'pcomplete-cycle-completions 'custom-type))
(defcustom eshell-cmpl-cycle-cutoff-length 5
(eshell-cmpl--custom-variable-docstring 'pcomplete-cycle-cutoff-length)
:type (get 'pcomplete-cycle-cutoff-length 'custom-type))
(defcustom eshell-cmpl-restore-window-delay 1
(eshell-cmpl--custom-variable-docstring 'pcomplete-restore-window-delay)
:type (get 'pcomplete-restore-window-delay 'custom-type))
(defcustom eshell-command-completion-function
(lambda ()
(pcomplete-here (eshell--complete-commands-list)))
(eshell-cmpl--custom-variable-docstring 'pcomplete-command-completion-function)
:type (get 'pcomplete-command-completion-function 'custom-type))
(defcustom eshell-cmpl-command-name-function
#'eshell-completion-command-name
(eshell-cmpl--custom-variable-docstring 'pcomplete-command-name-function)
:type (get 'pcomplete-command-name-function 'custom-type))
(defcustom eshell-default-completion-function
(lambda ()
(while (pcomplete-here
(pcomplete-dirs-or-entries
(cdr (assoc (funcall eshell-cmpl-command-name-function)
eshell-command-completions-alist))))))
(eshell-cmpl--custom-variable-docstring 'pcomplete-default-completion-function)
:type (get 'pcomplete-default-completion-function 'custom-type))
(defcustom eshell-cmpl-use-paring t
(eshell-cmpl--custom-variable-docstring 'pcomplete-use-paring)
:type (get 'pcomplete-use-paring 'custom-type))
;;; Functions:
(defun eshell-complete-lisp-symbol ()
"Try to complete the text around point as a Lisp symbol."
(interactive)
(let ((completion-at-point-functions '(elisp-completion-at-point)))
(completion-at-point)))
(defvar-keymap eshell-cmpl-mode-map
"C-i" #'completion-at-point
;; jww (1999-10-19): Will this work on anything but X?
"<backtab>" #'pcomplete-reverse
"M-?" #'completion-help-at-point
"C-M-i" #'eshell-complete-lisp-symbol
;; C-c prefix:
"C-c M-h" #'eshell-completion-help
"C-c TAB" #'pcomplete-expand-and-complete
"C-c C-i" #'pcomplete-expand-and-complete
"C-c SPC" #'pcomplete-expand)
(define-minor-mode eshell-cmpl-mode
"Minor mode that provides a keymap when `eshell-cmpl' active.
\\{eshell-cmpl-mode-map}"
:keymap eshell-cmpl-mode-map)
(defun eshell-cmpl-initialize () ;Called from `eshell-mode' via intern-soft!
"Initialize the completions module."
(setq-local pcomplete-command-completion-function
eshell-command-completion-function)
(setq-local pcomplete-command-name-function
eshell-cmpl-command-name-function)
(setq-local pcomplete-default-completion-function
eshell-default-completion-function)
(setq-local pcomplete-parse-arguments-function
#'eshell-complete-parse-arguments)
(setq-local pcomplete-file-ignore
eshell-cmpl-file-ignore)
(setq-local pcomplete-dir-ignore
eshell-cmpl-dir-ignore)
(setq-local pcomplete-remote-file-ignore
eshell-cmpl-remote-file-ignore)
(setq-local completion-ignore-case
eshell-cmpl-ignore-case)
(setq-local pcomplete-autolist
eshell-cmpl-autolist)
(setq-local pcomplete-recexact
eshell-cmpl-recexact)
(setq-local pcomplete-man-function
eshell-cmpl-man-function)
(setq-local pcomplete-compare-entry-function
eshell-cmpl-compare-entry-function)
(setq-local pcomplete-expand-before-complete
eshell-cmpl-expand-before-complete)
(setq-local pcomplete-cycle-completions
eshell-cmpl-cycle-completions)
(setq-local pcomplete-cycle-cutoff-length
eshell-cmpl-cycle-cutoff-length)
(setq-local pcomplete-restore-window-delay
eshell-cmpl-restore-window-delay)
(setq-local pcomplete-use-paring
eshell-cmpl-use-paring)
;; `comint-file-name-quote-list' should only be set after all the
;; load-hooks for any other extension modules have been run, which
;; is true at the time `eshell-mode-hook' is run
(add-hook 'eshell-mode-hook
(lambda ()
(setq-local comint-file-name-quote-list
eshell-special-chars-outside-quoting))
nil t)
(add-hook 'pcomplete-quote-arg-hook #'eshell-quote-backslash nil t)
(add-hook 'completion-at-point-functions
#'pcomplete-completions-at-point nil t)
(eshell-cmpl-mode))
(defun eshell-completion-command-name ()
"Return the command name, possibly sans globbing."
(let ((cmd (file-name-nondirectory (pcomplete-arg 'first))))
(setq cmd (if (and (> (length cmd) 0)
(eq (aref cmd 0) eshell-explicit-command-char))
(substring cmd 1)
cmd))
(if (eshell-under-windows-p)
(file-name-sans-extension cmd)
cmd)))
(defun eshell-completion-help ()
(interactive)
(if (= (point) eshell-last-output-end)
(describe-prefix-bindings)
(call-interactively 'pcomplete-help)))
(defun eshell--pcomplete-insert-tab ()
(if (not pcomplete-allow-modifications)
(throw 'pcompleted nil)
(insert-and-inherit "\t")
(throw 'pcompleted t)))
(defun eshell-complete--eval-argument-form (arg)
"Evaluate a single Eshell argument form ARG for the purposes of completion."
(condition-case err
(let* (;; Don't allow running commands; they could have
;; arbitrary side effects, which we don't want when we're
;; just performing completions!
(eshell-allow-commands)
;; Handle errors ourselves so that we can properly catch
;; `eshell-commands-forbidden'.
(eshell-handle-errors)
(result (eshell-do-eval `(eshell-commands ,arg) t)))
(cl-assert (eq (car result) 'quote))
(cadr result))
(eshell-commands-forbidden
(propertize "\0" 'eshell-argument-stub
(intern (format "%s-command" (cadr err)))))
(error
(lwarn 'eshell :error
"Failed to evaluate argument form during completion: %S" arg)
(propertize "\0" 'eshell-argument-stub 'error))))
;; Code stolen from `eshell-plain-command'.
(defun eshell-external-command-p (command)
"Whether an external command shall be called."
(let* ((esym (eshell-find-alias-function command))
(sym (or esym (intern-soft command))))
(not (and sym (fboundp sym)
(or esym eshell-prefer-lisp-functions
(not (eshell-search-path command)))))))
(defun eshell-complete-parse-arguments ()
"Parse the command line arguments for `pcomplete-argument'."
(when (and eshell-no-completion-during-jobs
eshell-foreground-command)
(eshell--pcomplete-insert-tab))
(let ((end (point-marker))
(begin (save-excursion (beginning-of-line) (point)))
args posns delim incomplete-arg)
(when (and pcomplete-allow-modifications
(memq this-command '(pcomplete-expand
pcomplete-expand-and-complete)))
(run-hook-with-args 'eshell-expand-input-functions begin end)
(if (= begin end)
(end-of-line))
(setq end (point-marker)))
;; Don't expand globs when parsing arguments; we want to pass any
;; globs to Pcomplete unaltered.
(declare-function eshell-parse-glob-chars "em-glob" ())
(let ((eshell-parse-argument-hook (remq #'eshell-parse-glob-chars
eshell-parse-argument-hook)))
(if (setq delim
(catch 'eshell-incomplete
(ignore
(setq args (eshell-parse-arguments begin end)))))
(cond ((member (car delim) '("{" "${" "$<"))
(setq begin (1+ (cadr delim))
args (eshell-parse-arguments begin end)))
((member (car delim) '("$'" "$\"" "#<"))
;; Add the (incomplete) argument to our arguments, and
;; note its position.
(setq args (append (nth 2 delim) (list (car delim)))
incomplete-arg t)
(push (- (nth 1 delim) 2) posns))
((member (car delim) '("(" "$("))
(throw 'pcompleted (elisp-completion-at-point)))
(t
(eshell--pcomplete-insert-tab)))))
(when (and (< begin end)
(get-text-property (1- end) 'comment))
(eshell--pcomplete-insert-tab))
(let ((pos (1- end)))
(while (>= pos begin)
(when (get-text-property pos 'arg-begin)
(push pos posns))
(setq pos (1- pos))))
(cl-assert (= (length args) (length posns)))
(let ((a args) (i 0) new-start)
(while a
;; If there's an unreplaced `eshell-operator' sigil, consider
;; the token after it the new start of our arguments.
(when (and (consp (car a))
(eq (caar a) 'eshell-operator))
(setq new-start i))
(setq a (cdr a)
i (1+ i)))
(when new-start
(setq args (nthcdr (1+ new-start) args)
posns (nthcdr (1+ new-start) posns))))
(cl-assert (= (length args) (length posns)))
(when (and args (not incomplete-arg)
(eq (char-syntax (char-before end)) ? )
(not (eq (char-before (1- end)) ?\\)))
(nconc args (list ""))
(nconc posns (list (point))))
;; Evaluate and expand Eshell forms.
(let (evaled-args evaled-posns)
(cl-mapc
(lambda (arg posn)
(pcase arg
(`(eshell-splice-args ,val)
(dolist (subarg (eshell-complete--eval-argument-form val))
(push subarg evaled-args)
(push posn evaled-posns)))
((pred listp)
(push (eshell-complete--eval-argument-form arg) evaled-args)
(push posn evaled-posns))
(_
(push arg evaled-args)
(push posn evaled-posns))))
args posns)
(setq args (nreverse evaled-args)
posns (nreverse evaled-posns)))
;; Determine, whether remote file names shall be completed. They
;; shouldn't for external commands, or when in a pipe. Respect
;; also `eshell-cmpl-remote-file-ignore', which could be set by
;; the user.
(setq-local pcomplete-remote-file-ignore
(or eshell-cmpl-remote-file-ignore
eshell-in-pipeline-p ; does not work
(eshell-external-command-p (car args))))
;; Convert arguments to forms that Pcomplete can understand.
(cons (mapcar
(lambda (arg)
(pcase arg
;; Expand ".../" etc that only Eshell understands to
;; the standard "../../".
((rx ".." (+ ".") "/")
(propertize (eshell-expand-multiple-dots arg)
'pcomplete-arg-value arg))
((pred stringp)
arg)
('nil
(propertize "" 'pcomplete-arg-value arg))
(_
(propertize (eshell-stringify arg)
'pcomplete-arg-value arg))))
args)
posns)))
(defun eshell--complete-commands-list ()
"Generate list of applicable, visible commands."
;; Building the commands list can take quite a while, especially over Tramp
;; (bug#41423), so do it lazily.
(let ((glob-name
;; When a command is specified using `eshell-explicit-command-char',
;; that char is not part of the command and hence not part of what
;; we complete. Adjust `pcomplete-stub' accordingly!
(if (and (> (length pcomplete-stub) 0)
(eq (aref pcomplete-stub 0) eshell-explicit-command-char))
(setq pcomplete-stub (substring pcomplete-stub 1))))
(filename (pcomplete-arg)))
;; Do not use `completion-table-dynamic' when completing a command file
;; name since it doesn't know about boundaries and would end up doing silly
;; things like adding a SPC char when completing to "/usr/sbin/".
;;
;; If you work on this function, be careful not to reintroduce bug#48995.
(if (file-name-directory filename)
(if eshell-force-execution
(pcomplete-dirs-or-entries nil #'file-readable-p)
(pcomplete-executables))
(completion-table-dynamic
(lambda (filename)
(let* ((paths (eshell-get-path))
(cwd (file-name-as-directory
(expand-file-name default-directory)))
(filepath "") (completions ()))
;; Go thru each path in the search path, finding completions.
(dolist (path paths)
(setq path (file-name-as-directory
(expand-file-name (or path "."))))
;; Go thru each completion found, to see whether it should
;; be used.
(dolist (file (and (file-accessible-directory-p path)
(file-name-all-completions filename path)))
(setq filepath (concat path file))
(if (and (not (member file completions)) ;
(or (string-equal path cwd)
(not (file-directory-p filepath)))
;; FIXME: Those repeated file tests end up
;; very costly over Tramp, we should cache the result.
(if eshell-force-execution
(file-readable-p filepath)
(file-executable-p filepath)))
(push file completions))))
;; Add aliases which are currently visible, and Lisp functions.
(pcomplete-uniquify-list
(if glob-name
completions
(setq completions
(append (if (fboundp 'eshell-alias-completions)
(eshell-alias-completions filename))
(eshell-winnow-list
(mapcar
(lambda (name)
(substring name 7))
(all-completions (concat "eshell/" filename)
obarray #'functionp))
nil '(eshell-find-alias-function))
completions))
(append (and (or eshell-show-lisp-completions
(and eshell-show-lisp-alternatives
(null completions)))
(all-completions filename obarray #'functionp))
completions)))))))))
(define-obsolete-function-alias 'eshell-pcomplete #'completion-at-point "27.1")
(provide 'em-cmpl)
;;; em-cmpl.el ends here