lisp/eshell/em-cmpl.el

   1 ;;; em-cmpl.el --- completion using the TAB key
   2
   3 ;; Copyright (C) 1999, 2000 Free Software Foundation
   4
   5 ;; Author: John Wiegley <johnw@gnu.org>
   6
   7 ;; This file is part of GNU Emacs.
   8
   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 2, or (at your option)
  12 ;; any later version.
  13
  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.
  18
  19 ;; You should have received a copy of the GNU General Public License
  20 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  21 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  22 ;; Boston, MA 02111-1307, USA.
  23
  24 (provide 'em-cmpl)
  25
  26 (eval-when-compile (require 'esh-maint))
  27
  28 (defgroup eshell-cmpl nil
  29   "This module provides a programmable completion function bound to
  30 the TAB key, which allows for completing command names, file names,
  31 variable names, arguments, etc."
  32   :tag "Argument completion"
  33   :group 'eshell-module)
  34
  35 ;;; Commentary:
  36
  37 ;; Eshell, by using the pcomplete package, provides a full
  38 ;; programmable completion facility that is comparable to shells like
  39 ;; tcsh or zsh.
  40 ;;
  41 ;; Completions are context-sensitive, which means that pressing <TAB>
  42 ;; after the command 'rmdir' will result in a list of directories,
  43 ;; while doing so after 'rm' will result in a list of all file
  44 ;; entries.
  45 ;;
  46 ;; Many builtin completion rules are provided, for commands such as
  47 ;; `cvs', or RedHat's `rpm' utility.  Adding new completion rules is
  48 ;; no more difficult than writing a plain Lisp functions, and they can
  49 ;; be debugged, profiled, and compiled using exactly the same
  50 ;; facilities (since in fact, they *are* just Lisp functions).  See
  51 ;; the definition of the function `pcomplete/make' for an example of
  52 ;; how to write a completion function.
  53 ;;
  54 ;; The completion facility is very easy to use.  Just press TAB.  If
  55 ;; there are a large number of possible completions, a buffer will
  56 ;; appear showing a list of them.  Completions may be selected from
  57 ;; that buffer using the mouse.  If no completion is selected, and the
  58 ;; user starts doing something else, the display buffer will
  59 ;; automatically disappear.
  60 ;;
  61 ;; If the list of possible completions is very small, Eshell will
  62 ;; "cycle" through them, selecting a different entry each time <TAB>
  63 ;; is pressed.  <S-TAB> may be used to cycle in the opposite
  64 ;; direction.
  65 ;;
  66 ;; Glob patterns can also be cycled.  For example, entering 'echo
  67 ;; x*<tab>' will cycle through all the filenames beginning with 'x'.
  68 ;; This is done because the glob list is treated as though it were a
  69 ;; list of possible completions.  Pressing <C-c SPC> will insert all
  70 ;; of the matching glob patterns at point.
  71 ;;
  72 ;; If a Lisp form is being entered, <TAB> will complete the Lisp
  73 ;; symbol name, in exactly the same way that <M-TAB> does in Emacs
  74 ;; Lisp mode.
  75 ;;
  76 ;; The list of possible completions can be viewed at any point by
  77 ;; pressing <M-?>.
  78 ;;
  79 ;; Finally, context-related help can be accessed by pressing <C-c i>.
  80 ;; This only works well if the completion function has provided Eshell
  81 ;; with sufficient pointers to locate the relevant help text.
  82
  83 ;;; User Variables:
  84
  85 (defcustom eshell-cmpl-load-hook '(eshell-cmpl-initialize)
  86   "*A list of functions to run when `eshell-cmpl' is loaded."
  87   :type 'hook
  88   :group 'eshell-cmpl)
  89
  90 (defcustom eshell-show-lisp-completions nil
  91   "*If non-nil, include Lisp functions in the command completion list.
  92 If this variable is nil, Lisp completion can still be done in command
  93 position by using M-TAB instead of TAB."
  94   :type 'boolean
  95   :group 'eshell-cmpl)
  96
  97 (defcustom eshell-show-lisp-alternatives t
  98   "*If non-nil, and no other completions found, show Lisp functions.
  99 Setting this variable means nothing if `eshell-show-lisp-completions'
 100 is non-nil."
 101   :type 'boolean
 102   :group 'eshell-cmpl)
 103
 104 (defcustom eshell-no-completion-during-jobs t
 105   "*If non-nil, don't allow completion while a process is running."
 106   :type 'boolean
 107   :group 'eshell-cmpl)
 108
 109 (defcustom eshell-command-completions-alist
 110   '(("acroread" . "\\.pdf\\'")
 111     ("xpdf"     . "\\.pdf\\'")
 112     ("ar"       . "\\.[ao]\\'")
 113     ("gcc"      . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
 114     ("g++"      . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
 115     ("cc"       . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
 116     ("CC"       . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
 117     ("acc"      . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
 118     ("bcc"      . "\\.[Cc]\\([Cc]\\|[Pp][Pp]\\)?\\'")
 119     ("objdump"  . "\\(\\`[^.]*\\|\\.[ao]\\)\\'")
 120     ("nm"       . "\\(\\`[^.]*\\|\\.[ao]\\)\\'")
 121     ("gdb"      . "\\`\\([^.]*\\|a\\.out\\)\\'")
 122     ("dbx"      . "\\`\\([^.]*\\|a\\.out\\)\\'")
 123     ("sdb"      . "\\`\\([^.]*\\|a\\.out\\)\\'")
 124     ("adb"      . "\\`\\([^.]*\\|a\\.out\\)\\'"))
 125   "*An alist that defines simple argument type correlations.
 126 This is provided for common commands, as a simplistic alternative
 127 to writing a completion function."
 128   :type '(repeat (cons string regexp))
 129   :group 'eshell-cmpl)
 130
 131 (defcustom eshell-cmpl-file-ignore "~\\'"
 132   (documentation-property 'pcomplete-file-ignore
 133                           'variable-documentation)
 134   :type (get 'pcomplete-file-ignore 'custom-type)
 135   :group 'eshell-cmpl)
 136
 137 (defcustom eshell-cmpl-dir-ignore
 138   (format "\\`\\(\\.\\.?\\|CVS\\)%c\\'" directory-sep-char)
 139   (documentation-property 'pcomplete-dir-ignore
 140                           'variable-documentation)
 141   :type (get 'pcomplete-dir-ignore 'custom-type)
 142   :group 'eshell-cmpl)
 143
 144 (defcustom eshell-cmpl-ignore-case (eshell-under-windows-p)
 145   (documentation-property 'pcomplete-ignore-case
 146                           'variable-documentation)
 147   :type (get 'pcomplete-ignore-case 'custom-type)
 148   :group 'eshell-cmpl)
 149
 150 (defcustom eshell-cmpl-autolist nil
 151   (documentation-property 'pcomplete-autolist
 152                           'variable-documentation)
 153   :type (get 'pcomplete-autolist 'custom-type)
 154   :group 'eshell-cmpl)
 155
 156 (defcustom eshell-cmpl-suffix-list (list directory-sep-char ?:)
 157   (documentation-property 'pcomplete-suffix-list
 158                           'variable-documentation)
 159   :type (get 'pcomplete-suffix-list 'custom-type)
 160   :group 'pcomplete)
 161
 162 (defcustom eshell-cmpl-recexact nil
 163   (documentation-property 'pcomplete-recexact
 164                           'variable-documentation)
 165   :type (get 'pcomplete-recexact 'custom-type)
 166   :group 'eshell-cmpl)
 167
 168 (defcustom eshell-cmpl-man-function 'man
 169   (documentation-property 'pcomplete-man-function
 170                           'variable-documentation)
 171   :type (get 'pcomplete-man-function 'custom-type)
 172   :group 'eshell-cmpl)
 173
 174 (defcustom eshell-cmpl-compare-entry-function 'file-newer-than-file-p
 175   (documentation-property 'pcomplete-compare-entry-function
 176                           'variable-documentation)
 177   :type (get 'pcomplete-compare-entry-function 'custom-type)
 178   :group 'eshell-cmpl)
 179
 180 (defcustom eshell-cmpl-expand-before-complete nil
 181   (documentation-property 'pcomplete-expand-before-complete
 182                           'variable-documentation)
 183   :type (get 'pcomplete-expand-before-complete 'custom-type)
 184   :group 'eshell-cmpl)
 185
 186 (defcustom eshell-cmpl-cycle-completions t
 187   (documentation-property 'pcomplete-cycle-completions
 188                           'variable-documentation)
 189   :type (get 'pcomplete-cycle-completions 'custom-type)
 190   :group 'eshell-cmpl)
 191
 192 (defcustom eshell-cmpl-cycle-cutoff-length 5
 193   (documentation-property 'pcomplete-cycle-cutoff-length
 194                           'variable-documentation)
 195   :type (get 'pcomplete-cycle-cutoff-length 'custom-type)
 196   :group 'eshell-cmpl)
 197
 198 (defcustom eshell-cmpl-restore-window-delay 1
 199   (documentation-property 'pcomplete-restore-window-delay
 200                           'variable-documentation)
 201   :type (get 'pcomplete-restore-window-delay 'custom-type)
 202   :group 'eshell-cmpl)
 203
 204 (defcustom eshell-command-completion-function
 205   (function
 206    (lambda ()
 207      (pcomplete-here (eshell-complete-commands-list))))
 208   (documentation-property 'pcomplete-command-completion-function
 209                           'variable-documentation)
 210   :type (get 'pcomplete-command-completion-function 'custom-type)
 211   :group 'eshell-cmpl)
 212
 213 (defcustom eshell-cmpl-command-name-function
 214   'eshell-completion-command-name
 215   (documentation-property 'pcomplete-command-name-function
 216                           'variable-documentation)
 217   :type (get 'pcomplete-command-name-function 'custom-type)
 218   :group 'eshell-cmpl)
 219
 220 (defcustom eshell-default-completion-function
 221   (function
 222    (lambda ()
 223      (while (pcomplete-here
 224              (pcomplete-dirs-or-entries
 225               (cdr (assoc (funcall eshell-cmpl-command-name-function)
 226                           eshell-command-completions-alist)))))))
 227   (documentation-property 'pcomplete-default-completion-function
 228                           'variable-documentation)
 229   :type (get 'pcomplete-default-completion-function 'custom-type)
 230   :group 'eshell-cmpl)
 231
 232 (defcustom eshell-cmpl-use-paring t
 233   (documentation-property 'pcomplete-use-paring 'variable-documentation)
 234   :type (get 'pcomplete-use-paring 'custom-type)
 235   :group 'eshell-cmpl)
 236
 237 ;;; Functions:
 238
 239 (defun eshell-cmpl-initialize ()
 240   "Initialize the completions module."
 241   (unless (fboundp 'pcomplete)
 242     (load "pcmpl-auto" t t))
 243   (set (make-local-variable 'pcomplete-command-completion-function)
 244        eshell-command-completion-function)
 245   (set (make-local-variable 'pcomplete-command-name-function)
 246        eshell-cmpl-command-name-function)
 247   (set (make-local-variable 'pcomplete-default-completion-function)
 248        eshell-default-completion-function)
 249   (set (make-local-variable 'pcomplete-parse-arguments-function)
 250        'eshell-complete-parse-arguments)
 251   (set (make-local-variable 'pcomplete-file-ignore)
 252        eshell-cmpl-file-ignore)
 253   (set (make-local-variable 'pcomplete-dir-ignore)
 254        eshell-cmpl-dir-ignore)
 255   (set (make-local-variable 'pcomplete-ignore-case)
 256        eshell-cmpl-ignore-case)
 257   (set (make-local-variable 'pcomplete-autolist)
 258        eshell-cmpl-autolist)
 259   (set (make-local-variable 'pcomplete-suffix-list)
 260        eshell-cmpl-suffix-list)
 261   (set (make-local-variable 'pcomplete-recexact)
 262        eshell-cmpl-recexact)
 263   (set (make-local-variable 'pcomplete-man-function)
 264        eshell-cmpl-man-function)
 265   (set (make-local-variable 'pcomplete-compare-entry-function)
 266        eshell-cmpl-compare-entry-function)
 267   (set (make-local-variable 'pcomplete-expand-before-complete)
 268        eshell-cmpl-expand-before-complete)
 269   (set (make-local-variable 'pcomplete-cycle-completions)
 270        eshell-cmpl-cycle-completions)
 271   (set (make-local-variable 'pcomplete-cycle-cutoff-length)
 272        eshell-cmpl-cycle-cutoff-length)
 273   (set (make-local-variable 'pcomplete-restore-window-delay)
 274        eshell-cmpl-restore-window-delay)
 275   (set (make-local-variable 'pcomplete-use-paring)
 276        eshell-cmpl-use-paring)
 277   ;; `pcomplete-arg-quote-list' should only be set after all the
 278   ;; load-hooks for any other extension modules have been run, which
 279   ;; is true at the time `eshell-mode-hook' is run
 280   (add-hook 'eshell-mode-hook
 281             (function
 282              (lambda ()
 283                (set (make-local-variable 'pcomplete-arg-quote-list)
 284                     eshell-special-chars-outside-quoting))) nil t)
 285   (add-hook 'pcomplete-quote-arg-hook 'eshell-quote-backslash nil t)
 286   (define-key eshell-mode-map [(meta tab)] 'lisp-complete-symbol)
 287   (define-key eshell-mode-map [(meta control ?i)] 'lisp-complete-symbol)
 288   (define-key eshell-command-map [(meta ?h)] 'eshell-completion-help)
 289   (define-key eshell-command-map [tab] 'pcomplete-expand-and-complete)
 290   (define-key eshell-command-map [(control ?i)]
 291     'pcomplete-expand-and-complete)
 292   (define-key eshell-command-map [space] 'pcomplete-expand)
 293   (define-key eshell-command-map [? ] 'pcomplete-expand)
 294   (define-key eshell-mode-map [tab] 'pcomplete)
 295   (define-key eshell-mode-map [(control ?i)] 'pcomplete)
 296   ;; jww (1999-10-19): Will this work on anything but X?
 297   (if (eshell-under-xemacs-p)
 298       (define-key eshell-mode-map [iso-left-tab] 'pcomplete-reverse)
 299     (define-key eshell-mode-map [(shift iso-lefttab)] 'pcomplete-reverse)
 300     (define-key eshell-mode-map [(shift control ?i)] 'pcomplete-reverse))
 301   (define-key eshell-mode-map [(meta ??)] 'pcomplete-list))
 302
 303 (defun eshell-completion-command-name ()
 304   "Return the command name, possibly sans globbing."
 305   (let ((cmd (file-name-nondirectory (pcomplete-arg 'first))))
 306     (setq cmd (if (and (> (length cmd) 0)
 307                        (eq (aref cmd 0) eshell-explicit-command-char))
 308                   (substring cmd 1)
 309                 cmd))
 310     (if (eshell-under-windows-p)
 311         (file-name-sans-extension cmd)
 312       cmd)))
 313
 314 (defun eshell-completion-help ()
 315   (interactive)
 316   (if (= (point) eshell-last-output-end)
 317       (describe-prefix-bindings)
 318     (call-interactively 'pcomplete-help)))
 319
 320 (defun eshell-complete-parse-arguments ()
 321   "Parse the command line arguments for `pcomplete-argument'."
 322   (when (and eshell-no-completion-during-jobs
 323              (eshell-interactive-process))
 324     (insert-and-inherit "\t")
 325     (throw 'pcompleted t))
 326   (let ((end (point-marker))
 327         (begin (save-excursion (eshell-bol) (point)))
 328         (posns (list t))
 329         args delim)
 330     (when (memq this-command '(pcomplete-expand
 331                                pcomplete-expand-and-complete))
 332       (run-hook-with-args 'eshell-expand-input-functions begin end)
 333       (if (= begin end)
 334           (end-of-line))
 335       (setq end (point-marker)))
 336     (if (setq delim
 337               (catch 'eshell-incomplete
 338                 (ignore
 339                  (setq args (eshell-parse-arguments begin end)))))
 340         (cond ((memq (car delim) '(?\{ ?\<))
 341                (setq begin (1+ (cadr delim))
 342                      args (eshell-parse-arguments begin end)))
 343               ((eq (car delim) ?\()
 344                (lisp-complete-symbol)
 345                (throw 'pcompleted t))
 346               (t
 347                (insert-and-inherit "\t")
 348                (throw 'pcompleted t))))
 349     (when (get-text-property (1- end) 'comment)
 350       (insert-and-inherit "\t")
 351       (throw 'pcompleted t))
 352     (let ((pos begin))
 353       (while (< pos end)
 354         (if (get-text-property pos 'arg-begin)
 355             (nconc posns (list pos)))
 356         (setq pos (1+ pos))))
 357     (setq posns (cdr posns))
 358     (assert (= (length args) (length posns)))
 359     (let ((a args)
 360           (i 0)
 361           l final)
 362       (while a
 363         (if (and (consp (car a))
 364                  (eq (caar a) 'eshell-operator))
 365             (setq l i))
 366         (setq a (cdr a) i (1+ i)))
 367       (and l
 368            (setq args (nthcdr (1+ l) args)
 369                  posns (nthcdr (1+ l) posns))))
 370     (assert (= (length args) (length posns)))
 371     (when (and args (eq (char-syntax (char-before end)) ? ))
 372       (nconc args (list ""))
 373       (nconc posns (list (point))))
 374     (cons (mapcar
 375            (function
 376             (lambda (arg)
 377               (let ((val
 378                      (if (listp arg)
 379                          (let ((result
 380                                 (eshell-do-eval
 381                                  (list 'eshell-commands arg) t)))
 382                            (assert (eq (car result) 'quote))
 383                            (cadr result))
 384                        arg)))
 385                 (if (numberp val)
 386                     (setq val (number-to-string val)))
 387                 (or val ""))))
 388            args)
 389           posns)))
 390
 391 (defun eshell-complete-commands-list ()
 392   "Generate list of applicable, visible commands."
 393   (let ((filename (pcomplete-arg)) glob-name)
 394     (if (file-name-directory filename)
 395         (pcomplete-executables)
 396       (if (and (> (length filename) 0)
 397                (eq (aref filename 0) eshell-explicit-command-char))
 398           (setq filename (substring filename 1)
 399                 pcomplete-stub filename
 400                 glob-name t))
 401       (let* ((paths (split-string (getenv "PATH") path-separator))
 402              (cwd (file-name-as-directory
 403                    (expand-file-name default-directory)))
 404              (path "") (comps-in-path ())
 405              (file "") (filepath "") (completions ()))
 406         ;; Go thru each path in the search path, finding completions.
 407         (while paths
 408           (setq path (file-name-as-directory
 409                       (expand-file-name (or (car paths) ".")))
 410                 comps-in-path
 411                 (and (file-accessible-directory-p path)
 412                      (file-name-all-completions filename path)))
 413           ;; Go thru each completion found, to see whether it should
 414           ;; be used.
 415           (while comps-in-path
 416             (setq file (car comps-in-path)
 417                   filepath (concat path file))
 418             (if (and (not (member file completions)) ;
 419                      (or (string-equal path cwd)
 420                          (not (file-directory-p filepath)))
 421                      (file-executable-p filepath))
 422                 (setq completions (cons file completions)))
 423             (setq comps-in-path (cdr comps-in-path)))
 424           (setq paths (cdr paths)))
 425         ;; Add aliases which are currently visible, and Lisp functions.
 426         (pcomplete-uniqify-list
 427          (if glob-name
 428              completions
 429            (setq completions
 430                  (append (and (eshell-using-module 'eshell-alias)
 431                               (funcall (symbol-function 'eshell-alias-completions)
 432                                        filename))
 433                          (eshell-winnow-list
 434                           (mapcar
 435                            (function
 436                             (lambda (name)
 437                               (substring name 7)))
 438                            (all-completions (concat "eshell/" filename)
 439                                             obarray 'functionp))
 440                           nil '(eshell-find-alias-function))
 441                          completions))
 442            (append (and (or eshell-show-lisp-completions
 443                             (and eshell-show-lisp-alternatives
 444                                  (null completions)))
 445                         (all-completions filename obarray 'functionp))
 446                    completions)))))))
 447
 448 ;;; Code:
 449
 450 ;;; em-cmpl.el ends here