lisp/eshell/em-dirs.el

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