code.delx.au - gnu-emacs/blob - lisp/eshell/em-cmpl.el

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