lisp/eshell/em-dirs.el

   1 ;;; em-dirs.el --- directory navigation commands
   2
   3 ;; Copyright (C) 1999-2011  Free Software Foundation, Inc.
   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 3 of the License, or
  12 ;; (at your option) 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.  If not, see <http://www.gnu.org/licenses/>.
  21
  22 ;;; Commentary:
  23
  24 ;; The only special feature that Eshell offers in the last-dir-ring.
  25 ;; To view the ring, enter:
  26 ;;
  27 ;;   cd =
  28 ;;
  29 ;; Changing to an index within the ring is done using:
  30 ;;
  31 ;;   cd -      ; same as cd -0
  32 ;;   cd -4
  33 ;;
  34 ;; Or, it is possible to change the first member in the ring which
  35 ;; matches a regexp:
  36 ;;
  37 ;;   cd =bcc   ; change to the last directory visited containing "bcc"
  38 ;;
  39 ;; This ring is maintained automatically, and is persisted across
  40 ;; Eshell sessions.  It is a separate mechanism from `pushd' and
  41 ;; `popd', and the two may be used at the same time.
  42
  43 ;;; Code:
  44
  45 (require 'eshell)
  46 (require 'ring)
  47 (require 'esh-opt)
  48
  49 ;;;###autoload
  50 (eshell-defgroup eshell-dirs nil
  51   "Directory navigation involves changing directories, examining the
  52 current directory, maintaining a directory stack, and also keeping
  53 track of a history of the last directory locations the user was in.
  54 Emacs does provide standard Lisp definitions of `pwd' and `cd', but
  55 they lack somewhat in feel from the typical shell equivalents."
  56   :tag "Directory navigation"
  57   :group 'eshell-module)
  58
  59 ;;; User Variables:
  60
  61 (defcustom eshell-dirs-load-hook nil
  62   "A hook that gets run when `eshell-dirs' is loaded."
  63   :version "24.1"                       ; removed eshell-dirs-initialize
  64   :type 'hook
  65   :group 'eshell-dirs)
  66
  67 (defcustom eshell-pwd-convert-function (if (eshell-under-windows-p)
  68                                            'expand-file-name
  69                                          'identity)
  70   "The function used to normalize the value of Eshell's `pwd'.
  71 The value returned by `pwd' is also used when recording the
  72 last-visited directory in the last-dir-ring, so it will affect the
  73 form of the list used by 'cd ='."
  74   :type '(radio (function-item file-truename)
  75                 (function-item expand-file-name)
  76                 (function-item identity)
  77                 (function :tag "Other"))
  78   :group 'eshell-dirs)
  79
  80 (defcustom eshell-ask-to-save-last-dir 'always
  81   "Determine if the last-dir-ring should be automatically saved.
  82 The last-dir-ring is always preserved when exiting an Eshell buffer.
  83 However, when Emacs is being shut down, this variable determines
  84 whether to prompt the user, or just save the ring.
  85 If set to nil, it means never ask whether to save the last-dir-ring.
  86 If set to t, always ask if any Eshell buffers are open at exit time.
  87 If set to `always', the list-dir-ring will always be saved, silently."
  88   :type '(choice (const :tag "Never" nil)
  89                  (const :tag "Ask" t)
  90                  (const :tag "Always save" always))
  91   :group 'eshell-dirs)
  92
  93 (defcustom eshell-cd-shows-directory nil
  94   "If non-nil, using `cd' will report the directory it changes to."
  95   :type 'boolean
  96   :group 'eshell-dirs)
  97
  98 (defcustom eshell-cd-on-directory t
  99   "If non-nil, do a cd if a directory is in command position."
 100   :type 'boolean
 101   :group 'eshell-dirs)
 102
 103 (defcustom eshell-directory-change-hook nil
 104   "A hook to run when the current directory changes."
 105   :type 'hook
 106   :group 'eshell-dirs)
 107
 108 (defcustom eshell-list-files-after-cd nil
 109   "If non-nil, call \"ls\" with any remaining args after doing a cd.
 110 This is provided for convenience, since the same effect is easily
 111 achieved by adding a function to `eshell-directory-change-hook' that
 112 calls \"ls\" and references `eshell-last-arguments'."
 113   :type 'boolean
 114   :group 'eshell-dirs)
 115
 116 (defcustom eshell-pushd-tohome nil
 117   "If non-nil, make pushd with no arg behave as 'pushd ~' (like `cd').
 118 This mirrors the optional behavior of tcsh."
 119   :type 'boolean
 120   :group 'eshell-dirs)
 121
 122 (defcustom eshell-pushd-dextract nil
 123   "If non-nil, make \"pushd +n\" pop the nth dir to the stack top.
 124 This mirrors the optional behavior of tcsh."
 125   :type 'boolean
 126   :group 'eshell-dirs)
 127
 128 (defcustom eshell-pushd-dunique nil
 129   "If non-nil, make pushd only add unique directories to the stack.
 130 This mirrors the optional behavior of tcsh."
 131   :type 'boolean
 132   :group 'eshell-dirs)
 133
 134 (defcustom eshell-dirtrack-verbose t
 135   "If non-nil, show the directory stack following directory change.
 136 This is effective only if directory tracking is enabled."
 137   :type 'boolean
 138   :group 'eshell-dirs)
 139
 140 (defcustom eshell-last-dir-ring-file-name
 141   (expand-file-name "lastdir" eshell-directory-name)
 142   "If non-nil, name of the file to read/write the last-dir-ring.
 143 See also `eshell-read-last-dir-ring' and `eshell-write-last-dir-ring'.
 144 If it is nil, the last-dir-ring will not be written to disk."
 145   :type 'file
 146   :group 'eshell-dirs)
 147
 148 (defcustom eshell-last-dir-ring-size 32
 149   "If non-nil, the size of the directory history ring.
 150 This ring is added to every time `cd' or `pushd' is used.  It simply
 151 stores the most recent directory locations Eshell has been in.  To
 152 return to the most recent entry, use 'cd -' (equivalent to 'cd -0').
 153 To return to an older entry, use 'cd -N', where N is an integer less
 154 than `eshell-last-dir-ring-size'.  To return to the last directory
 155 matching a particular regexp, use 'cd =REGEXP'.  To display the
 156 directory history list, use 'cd ='.
 157
 158 This mechanism is very similar to that provided by `pushd', except
 159 it's far more automatic.  `pushd' allows the user to decide which
 160 directories gets pushed, and its size is unlimited.
 161
 162 `eshell-last-dir-ring' is meant for users who don't use `pushd'
 163 explicity very much, but every once in a while would like to return to
 164 a previously visited directory without having to type in the whole
 165 thing again."
 166   :type 'integer
 167   :group 'eshell-dirs)
 168
 169 (defcustom eshell-last-dir-unique t
 170   "If non-nil, `eshell-last-dir-ring' contains only unique entries."
 171   :type 'boolean
 172   :group 'eshell-dirs)
 173
 174 ;;; Internal Variables:
 175
 176 (defvar eshell-dirstack nil
 177   "List of directories saved by pushd in the Eshell buffer.
 178 Thus, this does not include the current directory.")
 179
 180 (defvar eshell-last-dir-ring nil
 181   "The last directory that Eshell was in.")
 182
 183 ;;; Functions:
 184
 185 (defun eshell-dirs-initialize ()
 186   "Initialize the builtin functions for Eshell."
 187   (make-local-variable 'eshell-variable-aliases-list)
 188   (setq eshell-variable-aliases-list
 189         (append
 190          eshell-variable-aliases-list
 191          '(("-" (lambda (indices)
 192                   (if (not indices)
 193                       (unless (ring-empty-p eshell-last-dir-ring)
 194                         (expand-file-name
 195                          (ring-ref eshell-last-dir-ring 0)))
 196                     (expand-file-name
 197                      (eshell-apply-indices eshell-last-dir-ring indices)))))
 198            ("+" "PWD")
 199            ("PWD" (lambda (indices)
 200                     (expand-file-name (eshell/pwd))) t)
 201            ("OLDPWD" (lambda (indices)
 202                        (unless (ring-empty-p eshell-last-dir-ring)
 203                          (expand-file-name
 204                           (ring-ref eshell-last-dir-ring 0)))) t))))
 205
 206   (when eshell-cd-on-directory
 207     (make-local-variable 'eshell-interpreter-alist)
 208     (setq eshell-interpreter-alist
 209           (cons (cons 'eshell-lone-directory-p
 210                       'eshell-dirs-substitute-cd)
 211                 eshell-interpreter-alist)))
 212
 213   (add-hook 'eshell-parse-argument-hook
 214             'eshell-parse-user-reference nil t)
 215   (if (eshell-under-windows-p)
 216       (add-hook 'eshell-parse-argument-hook
 217                 'eshell-parse-drive-letter nil t))
 218
 219   (when (eshell-using-module 'eshell-cmpl)
 220     (add-hook 'pcomplete-try-first-hook
 221               'eshell-complete-user-reference nil t))
 222
 223   (make-local-variable 'eshell-dirstack)
 224   (make-local-variable 'eshell-last-dir-ring)
 225
 226   (if eshell-last-dir-ring-file-name
 227       (eshell-read-last-dir-ring))
 228   (unless eshell-last-dir-ring
 229     (setq eshell-last-dir-ring (make-ring eshell-last-dir-ring-size)))
 230
 231   (add-hook 'eshell-exit-hook 'eshell-write-last-dir-ring nil t)
 232
 233   (add-hook 'kill-emacs-hook 'eshell-save-some-last-dir))
 234
 235 (defun eshell-save-some-last-dir ()
 236   "Save the list-dir-ring for any open Eshell buffers."
 237   (dolist (buf (buffer-list))
 238     (if (buffer-live-p buf)
 239         (with-current-buffer buf
 240           (if (and eshell-mode
 241                    eshell-ask-to-save-last-dir
 242                    (or (eq eshell-ask-to-save-last-dir 'always)
 243                        (y-or-n-p
 244                         (format "Save last dir ring for Eshell buffer `%s'? "
 245                                 (buffer-name buf)))))
 246               (eshell-write-last-dir-ring))))))
 247
 248 (defun eshell-lone-directory-p (file)
 249   "Test whether FILE is just a directory name, and not a command name."
 250   (and (file-directory-p file)
 251        (or (file-name-directory file)
 252            (not (eshell-search-path file)))))
 253
 254 (defun eshell-dirs-substitute-cd (&rest args)
 255   "Substitute the given command for a call to `cd' on that name."
 256   (if (> (length args) 1)
 257       (error "%s: command not found" (car args))
 258     (throw 'eshell-replace-command
 259            (eshell-parse-command "cd" (eshell-flatten-list args)))))
 260
 261 (defun eshell-parse-user-reference ()
 262   "An argument beginning with ~ is a filename to be expanded."
 263   (when (and (not eshell-current-argument)
 264              (eq (char-after) ?~))
 265     (add-to-list 'eshell-current-modifiers 'expand-file-name)
 266     (forward-char)
 267     (char-to-string (char-before))))
 268
 269 (defun eshell-parse-drive-letter ()
 270   "An argument beginning with X:[^/] is a drive letter reference."
 271   (when (and (not eshell-current-argument)
 272              (looking-at "\\([A-Za-z]:\\)\\([^/\\\\]\\|\\'\\)"))
 273     (goto-char (match-end 1))
 274     (let* ((letter (match-string 1))
 275            (regexp (concat "\\`" letter))
 276            (path (eshell-find-previous-directory regexp)))
 277       (concat (or path letter) "/"))))
 278
 279 (defvar pcomplete-stub)
 280 (defvar pcomplete-last-completion-raw)
 281 (declare-function pcomplete-actual-arg "pcomplete")
 282 (declare-function pcomplete-uniqify-list "pcomplete")
 283
 284 (defun eshell-complete-user-reference ()
 285   "If there is a user reference, complete it."
 286   (let ((arg (pcomplete-actual-arg)))
 287     (when (string-match "\\`~[a-z]*\\'" arg)
 288       (setq pcomplete-stub (substring arg 1)
 289             pcomplete-last-completion-raw t)
 290       (throw 'pcomplete-completions
 291              (progn
 292                (eshell-read-user-names)
 293                (pcomplete-uniqify-list
 294                 (mapcar
 295                  (function
 296                   (lambda (user)
 297                     (file-name-as-directory (cdr user))))
 298                  eshell-user-names)))))))
 299
 300 (defun eshell/pwd (&rest args)
 301   "Change output from `pwd` to be cleaner."
 302   (let* ((path default-directory)
 303          (len (length path)))
 304     (if (and (> len 1)
 305              (eq (aref path (1- len)) ?/)
 306              (not (and (eshell-under-windows-p)
 307                        (string-match "\\`[A-Za-z]:[\\\\/]\\'" path))))
 308         (setq path (substring path 0 (1- (length path)))))
 309     (if eshell-pwd-convert-function
 310         (funcall eshell-pwd-convert-function path)
 311       path)))
 312
 313 (defun eshell-expand-multiple-dots (path)
 314   "Convert '...' to '../..', '....' to '../../..', etc..
 315
 316 With the following piece of advice, you can make this functionality
 317 available in most of Emacs, with the exception of filename completion
 318 in the minibuffer:
 319
 320   (defadvice expand-file-name
 321     (before translate-multiple-dots
 322             (filename &optional directory) activate)
 323     (setq filename (eshell-expand-multiple-dots filename)))"
 324   (while (string-match "\\(?:^\\|/\\)\\.\\.\\(\\.+\\)\\(?:$\\|/\\)" path)
 325     (let* ((extra-dots (match-string 1 path))
 326            (len (length extra-dots))
 327            replace-text)
 328       (while (> len 0)
 329         (setq replace-text (concat replace-text "/..")
 330               len (1- len)))
 331       (setq path
 332             (replace-match replace-text t t path 1))))
 333   path)
 334
 335 (defun eshell-find-previous-directory (regexp)
 336   "Find the most recent last-dir matching REGEXP."
 337   (let ((index 0)
 338         (len (ring-length eshell-last-dir-ring))
 339         oldpath)
 340     (if (> (length regexp) 0)
 341         (while (< index len)
 342           (setq oldpath (ring-ref eshell-last-dir-ring index))
 343           (if (string-match regexp oldpath)
 344               (setq index len)
 345             (setq oldpath nil
 346                   index (1+ index)))))
 347     oldpath))
 348
 349 (defvar dired-directory)
 350
 351 (defun eshell/cd (&rest args)           ; all but first ignored
 352   "Alias to extend the behavior of `cd'."
 353   (setq args (eshell-flatten-list args))
 354   (let ((path (car args))
 355         (subpath (car (cdr args)))
 356         (case-fold-search (eshell-under-windows-p))
 357         handled)
 358     (if (numberp path)
 359         (setq path (number-to-string path)))
 360     (if (numberp subpath)
 361         (setq subpath (number-to-string subpath)))
 362     (cond
 363      (subpath
 364       (let ((curdir (eshell/pwd)))
 365         (if (string-match path curdir)
 366             (setq path (replace-match subpath nil nil curdir))
 367           (error "Path substring '%s' not found" path))))
 368      ((and path (string-match "^-\\([0-9]*\\)$" path))
 369       (let ((index (match-string 1 path)))
 370         (setq path
 371               (ring-remove eshell-last-dir-ring
 372                            (if index
 373                                (string-to-number index)
 374                              0)))))
 375      ((and path (string-match "^=\\(.*\\)$" path))
 376       (let ((oldpath (eshell-find-previous-directory
 377                       (match-string 1 path))))
 378         (if oldpath
 379             (setq path oldpath)
 380           (let ((len (ring-length eshell-last-dir-ring))
 381                 (index 0))
 382             (if (= len 0)
 383                 (error "Directory ring empty"))
 384             (eshell-init-print-buffer)
 385             (while (< index len)
 386               (eshell-buffered-print
 387                (concat (number-to-string index) ": "
 388                        (ring-ref eshell-last-dir-ring index) "\n"))
 389               (setq index (1+ index)))
 390             (eshell-flush)
 391             (setq handled t)))))
 392      (path
 393       (setq path (eshell-expand-multiple-dots path))))
 394     (unless handled
 395       (setq dired-directory (or path "~"))
 396       (let ((curdir (eshell/pwd)))
 397         (unless (equal curdir dired-directory)
 398           (eshell-add-to-dir-ring curdir))
 399         (let ((result (cd dired-directory)))
 400           (and eshell-cd-shows-directory
 401                (eshell-printn result)))
 402         (run-hooks 'eshell-directory-change-hook)
 403         (if eshell-list-files-after-cd
 404             ;; Let-bind eshell-last-command around this?
 405             (eshell-plain-command "ls" (cdr args)))
 406         nil))))
 407
 408 (put 'eshell/cd 'eshell-no-numeric-conversions t)
 409
 410 (defun eshell-add-to-dir-ring (path)
 411   "Add PATH to the last-dir-ring, if applicable."
 412   (unless (and (not (ring-empty-p eshell-last-dir-ring))
 413                (equal path (ring-ref eshell-last-dir-ring 0)))
 414     (if eshell-last-dir-unique
 415         (let ((index 0)
 416               (len (ring-length eshell-last-dir-ring)))
 417           (while (< index len)
 418             (if (equal (ring-ref eshell-last-dir-ring index) path)
 419                 (ring-remove eshell-last-dir-ring index)
 420               (setq index (1+ index))))))
 421     (ring-insert eshell-last-dir-ring path)))
 422
 423 ;;; pushd [+n | dir]
 424 (defun eshell/pushd (&rest args)        ; all but first ignored
 425   "Implementation of pushd in Lisp."
 426   (let ((path (car args)))
 427     (cond
 428      ((null path)
 429       ;; no arg -- swap pwd and car of stack unless eshell-pushd-tohome
 430       (cond (eshell-pushd-tohome
 431              (eshell/pushd "~"))
 432             (eshell-dirstack
 433              (let ((old (eshell/pwd)))
 434                (eshell/cd (car eshell-dirstack))
 435                (setq eshell-dirstack (cons old (cdr eshell-dirstack)))
 436                (eshell/dirs t)))
 437             (t
 438              (error "pushd: No other directory"))))
 439      ((string-match "^\\+\\([0-9]\\)" path)
 440       ;; pushd +n
 441       (setq path (string-to-number (match-string 1 path)))
 442       (cond ((> path (length eshell-dirstack))
 443              (error "Directory stack not that deep"))
 444             ((= path 0)
 445              (error "Couldn't cd"))
 446             (eshell-pushd-dextract
 447              (let ((dir (nth (1- path) eshell-dirstack)))
 448                (eshell/popd path)
 449                (eshell/pushd (eshell/pwd))
 450                (eshell/cd dir)
 451                (eshell/dirs t)))
 452             (t
 453              (let* ((ds (cons (eshell/pwd) eshell-dirstack))
 454                     (dslen (length ds))
 455                     (front (nthcdr path ds))
 456                     (back (nreverse (nthcdr (- dslen path) (reverse ds))))
 457                     (new-ds (append front back)))
 458                (eshell/cd (car new-ds))
 459                (setq eshell-dirstack (cdr new-ds))
 460                (eshell/dirs t)))))
 461      (t
 462       ;; pushd <dir>
 463       (let ((old-wd (eshell/pwd)))
 464         (eshell/cd path)
 465         (if (or (null eshell-pushd-dunique)
 466                 (not (member old-wd eshell-dirstack)))
 467             (setq eshell-dirstack (cons old-wd eshell-dirstack)))
 468         (eshell/dirs t)))))
 469   nil)
 470
 471 (put 'eshell/pushd 'eshell-no-numeric-conversions t)
 472
 473 ;;; popd [+n]
 474 (defun eshell/popd (&rest args)
 475   "Implementation of popd in Lisp."
 476   (let ((ref (or (car args) "+0")))
 477     (unless (and (stringp ref)
 478                  (string-match "\\`\\([+-][0-9]+\\)\\'" ref))
 479       (error "popd: bad arg `%s'" ref))
 480     (setq ref (string-to-number (match-string 1 ref)))
 481     (cond ((= ref 0)
 482            (unless eshell-dirstack
 483              (error "popd: Directory stack empty"))
 484            (eshell/cd (car eshell-dirstack))
 485            (setq eshell-dirstack (cdr eshell-dirstack))
 486            (eshell/dirs t))
 487           ((<= (abs ref) (length eshell-dirstack))
 488            (let* ((ds (cons nil eshell-dirstack))
 489                   (cell (nthcdr (if (> ref 0)
 490                                     (1- ref)
 491                                   (+ (length eshell-dirstack) ref)) ds))
 492                   (dir (cadr cell)))
 493              (eshell/cd dir)
 494              (setcdr cell (cdr (cdr cell)))
 495              (setq eshell-dirstack (cdr ds))
 496              (eshell/dirs t)))
 497           (t
 498            (error "Couldn't popd"))))
 499   nil)
 500
 501 (put 'eshell/popd 'eshell-no-numeric-conversions t)
 502
 503 (defun eshell/dirs (&optional if-verbose)
 504   "Implementation of dirs in Lisp."
 505   (when (or (not if-verbose) eshell-dirtrack-verbose)
 506     (let* ((msg "")
 507            (ds (cons (eshell/pwd) eshell-dirstack))
 508            (home (expand-file-name "~/"))
 509            (homelen (length home)))
 510       (while ds
 511         (let ((dir (car ds)))
 512           (and (>= (length dir) homelen)
 513                (string= home (substring dir 0 homelen))
 514                (setq dir (concat "~/" (substring dir homelen))))
 515           (setq msg (concat msg (directory-file-name dir) " "))
 516           (setq ds (cdr ds))))
 517       msg)))
 518
 519 (defun eshell-read-last-dir-ring ()
 520   "Set the buffer's `eshell-last-dir-ring' from a history file."
 521   (let ((file eshell-last-dir-ring-file-name))
 522     (cond
 523      ((or (null file)
 524           (equal file "")
 525           (not (file-readable-p file)))
 526       nil)
 527      (t
 528       (let* ((count 0)
 529              (size eshell-last-dir-ring-size)
 530              (ring (make-ring size)))
 531         (with-temp-buffer
 532           (insert-file-contents file)
 533           ;; Save restriction in case file is already visited...
 534           ;; Watch for those date stamps in history files!
 535           (goto-char (point-max))
 536           (while (and (< count size)
 537                       (re-search-backward "^\\([^\n].*\\)$" nil t))
 538             (ring-insert-at-beginning ring (match-string 1))
 539             (setq count (1+ count)))
 540           ;; never allow the top element to equal the current
 541           ;; directory
 542           (while (and (not (ring-empty-p ring))
 543                       (equal (ring-ref ring 0) (eshell/pwd)))
 544             (ring-remove ring 0)))
 545         (setq eshell-last-dir-ring ring))))))
 546
 547 (defun eshell-write-last-dir-ring ()
 548   "Write the buffer's `eshell-last-dir-ring' to a history file."
 549   (let ((file eshell-last-dir-ring-file-name))
 550     (cond
 551      ((or (null file)
 552           (equal file "")
 553           (null eshell-last-dir-ring)
 554           (ring-empty-p eshell-last-dir-ring))
 555       nil)
 556      ((not (file-writable-p file))
 557       (message "Cannot write last-dir-ring file %s" file))
 558      (t
 559       (let* ((ring eshell-last-dir-ring)
 560              (index (ring-length ring)))
 561         (with-temp-buffer
 562           (while (> index 0)
 563             (setq index (1- index))
 564             (insert (ring-ref ring index) ?\n))
 565           (insert (eshell/pwd) ?\n)
 566           (eshell-with-private-file-modes
 567            (write-region (point-min) (point-max) file nil
 568                          'no-message))))))))
 569
 570 (provide 'em-dirs)
 571
 572 ;; Local Variables:
 573 ;; generated-autoload-file: "esh-groups.el"
 574 ;; End:
 575
 576 ;;; em-dirs.el ends here