lisp/eshell/em-dirs.el

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