lisp/eshell/em-alias.el

   1 ;;; em-alias.el --- creation and management of command aliases
   2
   3 ;; Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
   4 ;;   2008, 2009, 2010, 2011  Free Software Foundation, Inc.
   5
   6 ;; Author: John Wiegley <johnw@gnu.org>
   7
   8 ;; This file is part of GNU Emacs.
   9
  10 ;; GNU Emacs is free software: you can redistribute it and/or modify
  11 ;; it under the terms of the GNU General Public License as published by
  12 ;; the Free Software Foundation, either version 3 of the License, or
  13 ;; (at your option) any later version.
  14
  15 ;; GNU Emacs is distributed in the hope that it will be useful,
  16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 ;; GNU General Public License for more details.
  19
  20 ;; You should have received a copy of the GNU General Public License
  21 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  22
  23 ;;; Commentary:
  24
  25 ;; Command aliases greatly simplify the definition of new commands.
  26 ;; They exist as an alternative to alias functions, which are
  27 ;; otherwise quite superior, being more flexible and natural to the
  28 ;; Emacs Lisp environment (if somewhat trickier to define; [Alias
  29 ;; functions]).
  30 ;;
  31 ;;;_* Creating aliases
  32 ;;
  33 ;; The user interface is simple: type 'alias' followed by the command
  34 ;; name followed by the definition.  Argument references are made
  35 ;; using '$1', '$2', etc., or '$*'.  For example:
  36 ;;
  37 ;;   alias ll 'ls -l $*'
  38 ;;
  39 ;; This will cause the command 'll NEWS' to be replaced by 'ls -l
  40 ;; NEWS'.  This is then passed back to the command parser for
  41 ;; reparsing.{Only the command text specified in the alias definition
  42 ;; will be reparsed.  Argument references (such as '$*') are handled
  43 ;; using variable values, which means that the expansion will not be
  44 ;; reparsed, but used directly.}
  45 ;;
  46 ;; To delete an alias, specify its name without a definition:
  47 ;;
  48 ;;   alias ll
  49 ;;
  50 ;; Aliases are written to disk immediately after being defined or
  51 ;; deleted.  The filename in which they are kept is defined by the
  52 ;; variable eshell-aliases-file.
  53
  54 ;; The format of this file is quite basic.  It specifies the alias
  55 ;; definitions in almost exactly the same way that the user entered
  56 ;; them, minus any argument quoting (since interpolation is not done
  57 ;; when the file is read).  Hence, it is possible to add new aliases
  58 ;; to the alias file directly, using a text editor rather than the
  59 ;; `alias' command.  Or, this method can be used for editing aliases
  60 ;; that have already defined.
  61 ;;
  62 ;; Here is an example of a few different aliases, and they would
  63 ;; appear in the aliases file:
  64 ;;
  65 ;;   alias clean rm -fr **/.#*~
  66 ;;   alias commit cvs commit -m changes $*
  67 ;;   alias ll ls -l $*
  68 ;;   alias info (info)
  69 ;;   alias reindex glimpseindex -o ~/Mail
  70 ;;   alias compact for i in ~/Mail/**/*~*.bz2(Lk+50) { bzip2 -9v $i }
  71 ;;
  72 ;;;_* Auto-correction of bad commands
  73 ;;
  74 ;; When a user enters the same unknown command many times during a
  75 ;; session, it is likely that they are experiencing a spelling
  76 ;; difficulty associated with a certain command.  To combat this,
  77 ;; Eshell will offer to automatically define an alias for that
  78 ;; mispelled command, once a given tolerance threshold has been
  79 ;; reached.
  80
  81 ;; Whenever the same bad command name is encountered
  82 ;; `eshell-bad-command-tolerance' times, the user will be prompted in
  83 ;; the minibuffer to provide an alias name.  An alias definition will
  84 ;; then be created which will result in an equal call to the correct
  85 ;; name.  In this way, Eshell gradually learns about the commands that
  86 ;; the user mistypes frequently, and will automatically correct them!
  87 ;;
  88 ;; Note that a '$*' is automatically appended at the end of the alias
  89 ;; definition, so that entering it is unnecessary when specifying the
  90 ;; corrected command name.
  91
  92 ;;; Code:
  93
  94 (eval-when-compile
  95   (require 'esh-util))
  96 (require 'eshell)
  97
  98 ;;;###autoload
  99 (eshell-defgroup eshell-alias nil
 100   "Command aliases allow for easy definition of alternate commands."
 101   :tag "Command aliases"
 102   ;; :link '(info-link "(eshell)Command aliases")
 103   :group 'eshell-module)
 104
 105 (defcustom eshell-aliases-file (expand-file-name "alias" eshell-directory-name)
 106   "*The file in which aliases are kept.
 107 Whenever an alias is defined by the user, using the `alias' command,
 108 it will be written to this file.  Thus, alias definitions (and
 109 deletions) are always permanent.  This approach was chosen for the
 110 sake of simplicity, since that's pretty much the only benefit to be
 111 gained by using this module."
 112   :type 'file
 113   :group 'eshell-alias)
 114
 115 (defcustom eshell-bad-command-tolerance 3
 116   "*The number of failed commands to ignore before creating an alias."
 117   :type 'integer
 118   ;; :link '(custom-manual "(eshell)Auto-correction of bad commands")
 119   :group 'eshell-alias)
 120
 121 (defcustom eshell-alias-load-hook '(eshell-alias-initialize)
 122   "*A hook that gets run when `eshell-alias' is loaded."
 123   :type 'hook
 124   :group 'eshell-alias)
 125
 126 (defvar eshell-command-aliases-list nil
 127   "A list of command aliases currently defined by the user.
 128 Each element of this alias is a list of the form:
 129
 130   (NAME DEFINITION)
 131
 132 Where NAME is the textual name of the alias, and DEFINITION is the
 133 command string to replace that command with.
 134
 135 Note: this list should not be modified in your '.emacs' file.  Rather,
 136 any desired alias definitions should be declared using the `alias'
 137 command, which will automatically write them to the file named by
 138 `eshell-aliases-file'.")
 139
 140 (put 'eshell-command-aliases-list 'risky-local-variable t)
 141
 142 (defvar eshell-failed-commands-alist nil
 143   "An alist of command name failures.")
 144
 145 (defun eshell-alias-initialize ()
 146   "Initialize the alias handling code."
 147   (make-local-variable 'eshell-failed-commands-alist)
 148   (add-hook 'eshell-alternate-command-hook 'eshell-fix-bad-commands t t)
 149   (eshell-read-aliases-list)
 150   (add-hook 'eshell-named-command-hook 'eshell-maybe-replace-by-alias t t)
 151   (make-local-variable 'eshell-complex-commands)
 152   (add-to-list 'eshell-complex-commands 'eshell-command-aliased-p))
 153
 154 (defun eshell-command-aliased-p (name)
 155   (assoc name eshell-command-aliases-list))
 156
 157 (defun eshell/alias (&optional alias &rest definition)
 158   "Define an ALIAS in the user's alias list using DEFINITION."
 159   (if (not alias)
 160       (eshell-for alias eshell-command-aliases-list
 161         (eshell-print (apply 'format "alias %s %s\n" alias)))
 162     (if (not definition)
 163         (setq eshell-command-aliases-list
 164               (delq (assoc alias eshell-command-aliases-list)
 165                     eshell-command-aliases-list))
 166       (and (stringp definition)
 167            (set-text-properties 0 (length definition) nil definition))
 168       (let ((def (assoc alias eshell-command-aliases-list))
 169             (alias-def (list alias
 170                              (eshell-flatten-and-stringify definition))))
 171         (if def
 172             (setq eshell-command-aliases-list
 173                   (delq def eshell-command-aliases-list)))
 174         (setq eshell-command-aliases-list
 175               (cons alias-def eshell-command-aliases-list))))
 176     (eshell-write-aliases-list))
 177   nil)
 178
 179 (defvar pcomplete-stub)
 180 (autoload 'pcomplete-here "pcomplete")
 181
 182 (defun pcomplete/eshell-mode/alias ()
 183   "Completion function for Eshell's `alias' command."
 184   (pcomplete-here (eshell-alias-completions pcomplete-stub)))
 185
 186 (defun eshell-read-aliases-list ()
 187   "Read in an aliases list from `eshell-aliases-file'."
 188   (let ((file eshell-aliases-file))
 189     (when (file-readable-p file)
 190       (setq eshell-command-aliases-list
 191             (with-temp-buffer
 192               (let (eshell-command-aliases-list)
 193                 (insert-file-contents file)
 194                 (while (not (eobp))
 195                   (if (re-search-forward
 196                        "^alias\\s-+\\(\\S-+\\)\\s-+\\(.+\\)")
 197                       (setq eshell-command-aliases-list
 198                             (cons (list (match-string 1)
 199                                         (match-string 2))
 200                                   eshell-command-aliases-list)))
 201                   (forward-line 1))
 202                 eshell-command-aliases-list))))))
 203
 204 (defun eshell-write-aliases-list ()
 205   "Write out the current aliases into `eshell-aliases-file'."
 206   (if (file-writable-p (file-name-directory eshell-aliases-file))
 207       (let ((eshell-current-handles
 208              (eshell-create-handles eshell-aliases-file 'overwrite)))
 209         (eshell/alias)
 210         (eshell-close-handles 0))))
 211
 212 (defsubst eshell-lookup-alias (name)
 213   "Check whether NAME is aliased.  Return the alias if there is one."
 214   (assoc name eshell-command-aliases-list))
 215
 216 (defvar eshell-prevent-alias-expansion nil)
 217
 218 (defun eshell-maybe-replace-by-alias (command args)
 219   "If COMMAND has an alias definition, call that instead using ARGS."
 220   (unless (and eshell-prevent-alias-expansion
 221                (member command eshell-prevent-alias-expansion))
 222     (let ((alias (eshell-lookup-alias command)))
 223       (if alias
 224           (throw 'eshell-replace-command
 225                  (list
 226                   'let
 227                   (list
 228                    (list 'eshell-command-name
 229                          (list 'quote eshell-last-command-name))
 230                    (list 'eshell-command-arguments
 231                          (list 'quote eshell-last-arguments))
 232                    (list 'eshell-prevent-alias-expansion
 233                          (list 'quote
 234                                (cons command
 235                                      eshell-prevent-alias-expansion))))
 236                   (eshell-parse-command (nth 1 alias))))))))
 237
 238 (defun eshell-alias-completions (name)
 239   "Find all possible completions for NAME.
 240 These are all the command aliases which begin with NAME."
 241   (let (completions)
 242     (eshell-for alias eshell-command-aliases-list
 243       (if (string-match (concat "^" name) (car alias))
 244           (setq completions (cons (car alias) completions))))
 245     completions))
 246
 247 (defun eshell-fix-bad-commands (name)
 248   "If the user repeatedly a bad command NAME, make an alias for them."
 249   (ignore
 250    (unless (file-name-directory name)
 251      (let ((entry (assoc name eshell-failed-commands-alist)))
 252        (if (not entry)
 253            (setq eshell-failed-commands-alist
 254                  (cons (cons name 1) eshell-failed-commands-alist))
 255          (if (< (cdr entry) eshell-bad-command-tolerance)
 256              (setcdr entry (1+ (cdr entry)))
 257            (let ((alias (concat
 258                          (read-string
 259                           (format "Define alias for \"%s\": " name))
 260                          " $*")))
 261              (eshell/alias name alias)
 262              (throw 'eshell-replace-command
 263                     (list
 264                      'let
 265                      (list
 266                       (list 'eshell-command-name
 267                             (list 'quote name))
 268                       (list 'eshell-command-arguments
 269                             (list 'quote eshell-last-arguments))
 270                       (list 'eshell-prevent-alias-expansion
 271                             (list 'quote
 272                                   (cons name
 273                                         eshell-prevent-alias-expansion))))
 274                      (eshell-parse-command alias))))))))))
 275
 276 (provide 'em-alias)
 277
 278 ;; Local Variables:
 279 ;; generated-autoload-file: "esh-groups.el"
 280 ;; End:
 281
 282 ;; arch-tag: 8b018fc1-4e07-4ccc-aa73-c0a1ba361f82
 283 ;;; em-alias.el ends here