lisp/eshell/em-dirs.el

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