lisp/recentf.el

   1 ;; recentf.el --- setup a menu of recently opened files
   2
   3 ;; Copyright (C) 1999, 2000 Free Software Foundation, Inc.
   4
   5 ;; Author: David Ponce <david.ponce@wanadoo.fr>
   6 ;; Created: July 19 1999
   7 ;; Keywords: customization
   8
   9 ;; This file is part of GNU Emacs.
  10
  11 ;; GNU Emacs is free software; you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation; either version 2, or (at your option)
  14 ;; any later version.
  15
  16 ;; GNU Emacs is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  23 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  24 ;; Boston, MA 02111-1307, USA.
  25
  26 ;;; Commentary:
  27
  28 ;; This package maintains a menu for visiting files that were operated
  29 ;; on recently. When enabled a new "Open Recent" submenu is displayed
  30 ;; in the "Files" menu. The recent files list is automatically saved
  31 ;; across Emacs sessions.  You can customize the number of recent
  32 ;; files displayed, the location of the menu and others options (see
  33 ;; the source code for details).  To install and use, put the file on
  34 ;; your Emacs-Lisp load path and add the following into your ~/.emacs
  35 ;; startup file:
  36 ;;
  37 ;;  (require 'recentf)
  38 ;;  (recentf-mode 1)
  39
  40 ;;; Code:
  41
  42 (require 'easymenu)
  43 (require 'wid-edit)
  44
  45 (defconst recentf-save-file-header
  46   ";;; Automatically generated by `recentf' on %s.\n"
  47   "Header to be written into the `recentf-save-file'.")
  48
  49 (defvar recentf-list nil
  50   "List of recently opened files.")
  51
  52 (defvar recentf-update-menu-p t
  53   "Non-nil if the recentf menu must be updated.")
  54
  55 (defvar recentf-initialized-p nil
  56   "Non-nil if recentf already initialized.")
  57
  58 ;; IMPORTANT: This function must be defined before the following defcustoms
  59 ;; because it is used in their :set clause. To avoid byte-compiler warnings
  60 ;; the `symbol-value' function is used to access the `recentf-menu-path'
  61 ;; and `recentf-menu-title' values.
  62 (defun recentf-menu-customization-changed (sym val)
  63   "Function called when menu customization has changed.
  64 It removes the recentf menu and forces its complete redrawing."
  65   (when recentf-initialized-p
  66     (easy-menu-remove-item nil
  67                            (symbol-value 'recentf-menu-path)
  68                            (symbol-value 'recentf-menu-title))
  69     (setq recentf-update-menu-p t))
  70   (custom-set-default sym val))
  71
  72 (defgroup recentf nil
  73   "Maintain a menu of recently opened files."
  74   :version "21.1"
  75   :group 'files)
  76
  77 (defcustom recentf-max-saved-items 20
  78   "*Maximum number of items saved to `recentf-save-file'."
  79   :group 'recentf
  80   :type 'integer)
  81
  82 (defcustom recentf-save-file (expand-file-name "~/.recentf")
  83   "*File to save `recentf-list' into."
  84   :group 'recentf
  85   :type 'file)
  86
  87 (defcustom recentf-exclude nil
  88   "*List of regexps for filenames excluded from `recentf-list'."
  89   :group 'recentf
  90   :type '(repeat regexp))
  91
  92 (defcustom recentf-menu-title "Open Recent"
  93   "*Name of the recentf menu."
  94   :group 'recentf
  95   :type 'string
  96   :set 'recentf-menu-customization-changed)
  97
  98 (defcustom recentf-menu-path '("files")
  99   "*Path where to add the recentf menu.
 100 If nil add it at top-level (see also `easy-menu-change')."
 101   :group 'recentf
 102   :type '(choice (const :tag "Top Level" nil)
 103                  (sexp :tag "Menu Path"))
 104   :set 'recentf-menu-customization-changed)
 105
 106 (defcustom recentf-menu-before "open-file"
 107   "*Name of the menu before which the recentf menu will be added.
 108 If nil add it at end of menu (see also `easy-menu-change')."
 109   :group 'recentf
 110   :type '(choice (string :tag "Name")
 111                  (const :tag "Last" nil))
 112   :set 'recentf-menu-customization-changed)
 113
 114 (defcustom recentf-menu-action 'recentf-find-file
 115   "*Function to invoke with a filename item of the recentf menu.
 116 The default action `recentf-find-file' calls `find-file' to edit an
 117 existing file.  If the file does not exist or is not readable, it is
 118 not edited and its name is removed from `recentf-list'. You can use
 119 `find-file' instead to open non-existing files and keep them in the
 120 list of recently opened files."
 121   :group 'recentf
 122   :type 'function
 123   :set 'recentf-menu-customization-changed)
 124
 125 (defcustom recentf-max-menu-items 10
 126   "*Maximum number of items in the recentf menu."
 127   :group 'recentf
 128   :type 'integer
 129   :set 'recentf-menu-customization-changed)
 130
 131 (defcustom recentf-menu-filter nil
 132   "*Function used to filter files displayed in the recentf menu.
 133 Nil means no filter.  The following functions are predefined:
 134
 135 - - `recentf-sort-ascending' to sort menu items in ascending order.
 136 - - `recentf-sort-descending' to sort menu items in descending order.
 137 - - `recentf-sort-basenames-ascending' to sort file names in descending order.
 138 - - `recentf-sort-basenames-descending' to sort file names in descending order.
 139 - - `recentf-show-basenames' to show file names (no directories) in menu items.
 140 - - `recentf-show-basenames-ascending' to show file names in ascending order.
 141 - - `recentf-show-basenames-descending' to show file names in descending order.
 142 - - `recentf-relative-filter' to show file names relative to `default-directory'.
 143
 144 The filter function is called with one argument, the list of menu elements
 145 used to build the menu and must return a new list of menu elements (see
 146 `recentf-menu-elements' for menu element form)."
 147   :group 'recentf
 148   :type 'function
 149   :set 'recentf-menu-customization-changed)
 150
 151 (defcustom recentf-menu-append-commands-p t
 152   "*If not-nil command items are appended to the menu."
 153   :group 'recentf
 154   :type 'boolean
 155   :set 'recentf-menu-customization-changed)
 156
 157 (defcustom recentf-keep-non-readable-files-p nil
 158   "*If nil (default), non-readable files are not kept in `recentf-list'."
 159   :group 'recentf
 160   :type 'boolean
 161   :require 'recentf
 162   :initialize 'custom-initialize-default
 163   :set (lambda (sym val)
 164          (if val
 165              (remove-hook 'kill-buffer-hook 'recentf-remove-file-hook)
 166            (add-hook 'kill-buffer-hook 'recentf-remove-file-hook))
 167          (custom-set-default sym val)))
 168
 169 (defcustom recentf-mode nil
 170   "Toggle recentf mode.
 171 When recentf mode is enabled, it maintains a menu for visiting files that
 172 were operated on recently.
 173 Setting this variable directly does not take effect;
 174 use either \\[customize] or the function `recentf-mode'."
 175   :set (lambda (symbol value)
 176          (recentf-mode (or value 0)))
 177   :initialize 'custom-initialize-default
 178   :type 'boolean
 179   :group 'recentf
 180   :require 'recentf)
 181
 182 (defcustom recentf-load-hook nil
 183    "*Normal hook run at end of loading the `recentf' package."
 184   :group 'recentf
 185   :type 'hook)
 186
 187 ;;;###autoload
 188 (defun recentf-mode (&optional arg)
 189   "Toggle recentf mode.
 190 With prefix ARG, turn recentf mode on if and only if ARG is positive.
 191 Returns the new status of recentf mode (non-nil means on).
 192
 193 When recentf mode is enabled, it maintains a menu for visiting files that
 194 were operated on recently."
 195   (interactive "P")
 196   (let ((on-p (if arg
 197                   (> (prefix-numeric-value arg) 0)
 198                 (not recentf-mode))))
 199     (if on-p
 200         (unless recentf-initialized-p
 201           (setq recentf-initialized-p t)
 202           (if (file-readable-p recentf-save-file)
 203               (load-file recentf-save-file))
 204           (setq recentf-update-menu-p t)
 205           (add-hook 'find-file-hooks       'recentf-add-file-hook)
 206           (add-hook 'write-file-hooks      'recentf-add-file-hook)
 207           ;;    (add-hook 'activate-menubar-hook 'recentf-update-menu-hook)
 208           (add-hook 'menu-bar-update-hook  'recentf-update-menu-hook)
 209           (add-hook 'kill-emacs-hook       'recentf-save-list))
 210       (when recentf-initialized-p
 211         (setq recentf-initialized-p nil)
 212         (recentf-save-list)
 213         (easy-menu-remove-item nil recentf-menu-path recentf-menu-title)
 214         (remove-hook 'find-file-hooks       'recentf-add-file-hook)
 215         (remove-hook 'write-file-hooks      'recentf-add-file-hook)
 216         ;;    (remove-hook 'activate-menubar-hook 'recentf-update-menu-hook)
 217         (remove-hook 'menu-bar-update-hook  'recentf-update-menu-hook)
 218         (remove-hook 'kill-emacs-hook       'recentf-save-list)))
 219     (setq recentf-mode on-p)))
 220
 221 (defun recentf-add-file-hook ()
 222   "Insert the name of the file just opened or written into `recentf-list'."
 223   (and buffer-file-name (recentf-add-file buffer-file-name))
 224   nil)
 225
 226 (defun recentf-remove-file-hook ()
 227   "When a buffer is killed remove a non readable file from `recentf-list'."
 228   (and buffer-file-name (recentf-remove-if-non-readable buffer-file-name))
 229   nil)
 230
 231 (defun recentf-update-menu-hook ()
 232   "Update the recentf menu from the current `recentf-list'."
 233   (when recentf-update-menu-p
 234     (condition-case nil
 235         (progn
 236           (setq recentf-update-menu-p nil)
 237           (easy-menu-change recentf-menu-path
 238                             recentf-menu-title
 239                             (recentf-make-menu-items)
 240                             recentf-menu-before))
 241       (error nil))))
 242
 243 ;;;###autoload
 244 (defun recentf-save-list ()
 245   "Save the current `recentf-list' to the file `recentf-save-file'."
 246   (interactive)
 247   (let ((saved-list (recentf-elements recentf-max-saved-items)))
 248     (with-temp-buffer
 249       (erase-buffer)
 250       (insert (format recentf-save-file-header (current-time-string)))
 251       (insert "(setq recentf-list\n      '(\n")
 252       (mapcar '(lambda (e)
 253                  (insert (format "        %S\n" e)))
 254               saved-list)
 255       (insert "        ))")
 256       (if (file-writable-p recentf-save-file)
 257           (write-region (point-min) (point-max) recentf-save-file))
 258       (kill-buffer (current-buffer))))
 259   nil)
 260
 261 (defvar recentf-edit-selected-items nil
 262   "Used by `recentf-edit-list' to hold the list of files to be deleted
 263 from `recentf-list'.")
 264
 265 (defun recentf-edit-list-action (widget &rest ignore)
 266   "Checkbox widget action used by `recentf-edit-list' to select/unselect a file."
 267   (let ((value (widget-get widget ':tag)))
 268     ;; if value is already in the selected items
 269     (if (memq value recentf-edit-selected-items)
 270         ;; then remove it
 271         (progn
 272           (setq recentf-edit-selected-items
 273                 (delq value recentf-edit-selected-items))
 274           (message "%s removed from selection." value))
 275       ;; else add it
 276       (progn
 277         (setq recentf-edit-selected-items
 278               (nconc (list value) recentf-edit-selected-items))
 279         (message "%s added to selection." value)))))
 280
 281 ;;;###autoload
 282 (defun recentf-edit-list ()
 283   "Allow the user to edit the files that are kept in the recent list."
 284   (interactive)
 285   (with-current-buffer (get-buffer-create (concat "*" recentf-menu-title " - Edit list*"))
 286     (switch-to-buffer (current-buffer))
 287     (kill-all-local-variables)
 288     (let ((inhibit-read-only t))
 289       (erase-buffer))
 290     (let ((all (overlay-lists)))
 291       ;; Delete all the overlays.
 292       (mapcar 'delete-overlay (car all))
 293       (mapcar 'delete-overlay (cdr all)))
 294     (setq recentf-edit-selected-items nil)
 295     ;; Insert the dialog header
 296     (widget-insert "Select the files to be deleted from the 'recentf-list'.\n\n")
 297     (widget-insert "Click on Ok to update the list or on Cancel to quit.\n" )
 298     ;; Insert the list of files as checkboxes
 299     (mapcar '(lambda (item)
 300                (widget-create 'checkbox
 301                               :value nil ; unselected checkbox
 302                               :format "\n %[%v%]  %t"
 303                               :tag item
 304                               :notify 'recentf-edit-list-action))
 305             recentf-list)
 306     (widget-insert "\n\n")
 307     ;; Insert the Ok button
 308     (widget-create 'push-button
 309                    :notify (lambda (&rest ignore)
 310                              (if recentf-edit-selected-items
 311                                  (progn (kill-buffer (current-buffer))
 312                                         (mapcar '(lambda (item)
 313                                                    (setq recentf-list
 314                                                          (delq item recentf-list)))
 315                                                 recentf-edit-selected-items)
 316                                         (message "%S file(s) removed from the list"
 317                                                  (length recentf-edit-selected-items))
 318                                         (setq recentf-update-menu-p t))
 319                                (message "No file selected.")))
 320                    "Ok")
 321     (widget-insert " ")
 322     ;; Insert the Cancel button
 323     (widget-create 'push-button
 324                    :notify (lambda (&rest ignore)
 325                              (kill-buffer (current-buffer))
 326                              (message "Command canceled."))
 327                    "Cancel")
 328     (use-local-map widget-keymap)
 329     (widget-setup)
 330     (goto-char (point-min))))
 331
 332 ;;;###autoload
 333 (defun recentf-cleanup ()
 334   "Remove all non-readable and excluded files from `recentf-list'."
 335   (interactive)
 336   (let ((count (length recentf-list)))
 337     (setq recentf-list
 338           (delq nil
 339                 (mapcar '(lambda (filename)
 340                            (and (file-readable-p filename)
 341                                 (recentf-include-p filename)
 342                                 filename))
 343                         recentf-list)))
 344     (setq count (- count (length recentf-list)))
 345     (message "%s removed from the list"
 346              (cond ((= count 0) "No file")
 347                    ((= count 1) "One file")
 348                    (t (format "%d files" count)))))
 349   (setq recentf-update-menu-p t))
 350
 351 (defun recentf-open-more-files-action (widget &rest ignore)
 352   "Button widget action used by `recentf-open-more-files' to open a file."
 353   (kill-buffer (current-buffer))
 354   (funcall recentf-menu-action (widget-value widget)))
 355
 356 ;;;###autoload
 357 (defun recentf-open-more-files ()
 358   "Allow the user to open files that are not in the menu."
 359   (interactive)
 360   (with-current-buffer (get-buffer-create (concat "*" recentf-menu-title " - More*"))
 361     (switch-to-buffer (current-buffer))
 362     (kill-all-local-variables)
 363     (let ((inhibit-read-only t))
 364       (erase-buffer))
 365     (let ((all (overlay-lists)))
 366       ;; Delete all the overlays.
 367       (mapcar 'delete-overlay (car all))
 368       (mapcar 'delete-overlay (cdr all)))
 369     ;; Insert the dialog header
 370     (widget-insert "Click on a file to open it or on Cancel to quit.\n\n")
 371     ;; Insert the list of files as buttons
 372     (mapcar '(lambda (menu-element)
 373                (let ((menu-item (car menu-element))
 374                      (file-path (cdr menu-element)))
 375                  (widget-create 'push-button
 376                                 :button-face 'default
 377                                 :tag menu-item
 378                                 :help-echo (concat "Open " file-path)
 379                                 :format "%[%t%]"
 380                                 :notify 'recentf-open-more-files-action
 381                                 file-path)
 382                  (widget-insert "\n")))
 383             (funcall (or recentf-menu-filter 'identity)
 384                      (mapcar '(lambda (item) (cons item item))
 385                              (nthcdr recentf-max-menu-items recentf-list))))
 386     (widget-insert "\n")
 387     ;; Insert the Cancel button
 388     (widget-create 'push-button
 389                    :notify (lambda (&rest ignore)
 390                              (kill-buffer (current-buffer))
 391                              (message "Command canceled."))
 392                    "Cancel")
 393     (use-local-map widget-keymap)
 394     (widget-setup)
 395     (goto-char (point-min))))
 396
 397 (defvar recentf-menu-items-for-commands
 398   (list ["Cleanup list" recentf-cleanup t]
 399         ["Edit list..." recentf-edit-list t]
 400         ["Save list now" recentf-save-list t]
 401         (vector "Recentf Options..." '(customize-group "recentf") t))
 402   "List of menu items for recentf commands.")
 403
 404 (defun recentf-make-menu-items ()
 405   "Make menu items from `recentf-list'."
 406   (let ((file-items
 407          (mapcar 'recentf-make-menu-item
 408                  (funcall (or recentf-menu-filter 'identity)
 409                           (recentf-menu-elements recentf-max-menu-items)))))
 410     (append (or file-items (list ["No files" t nil]))
 411             (and (< recentf-max-menu-items (length recentf-list))
 412                  (list ["More..." recentf-open-more-files t]))
 413             (and recentf-menu-append-commands-p
 414                  (cons ["---" nil nil]
 415                        recentf-menu-items-for-commands)))))
 416
 417 (defun recentf-make-menu-item (menu-element)
 418   "Make a menu item from a menu element (see `recentf-menu-elements')."
 419   (vector (car menu-element) (list recentf-menu-action (cdr menu-element)) t))
 420
 421 (defun recentf-add-file (filename)
 422   "Add or move FILENAME at the beginning of `recentf-list'.
 423 Does nothing if FILENAME matches one of the `recentf-exclude' regexps."
 424   (when (recentf-include-p filename)
 425     (setq recentf-list (cons filename (delete filename recentf-list)))
 426     (setq recentf-update-menu-p t)))
 427
 428 (defun recentf-remove-if-non-readable (filename)
 429   "Remove FILENAME from `recentf-list' if not readable."
 430   (unless (file-readable-p filename)
 431     (setq recentf-list (delete filename recentf-list))
 432     (setq recentf-update-menu-p t)))
 433
 434 (defun recentf-find-file (filename)
 435   "Edit file FILENAME using `find-file'.
 436 If FILENAME is not readable it is removed from `recentf-list'."
 437   (if (file-readable-p filename)
 438       (find-file filename)
 439     (progn
 440       (message "File `%s' not found." filename)
 441       (setq recentf-list (delete filename recentf-list))
 442       (setq recentf-update-menu-p t))))
 443
 444 (defun recentf-include-p (filename)
 445   "Return t if FILENAME matches none of the `recentf-exclude' regexps."
 446   (let ((rl recentf-exclude))
 447     (while (and rl (not (string-match (car rl) filename)))
 448       (setq rl (cdr rl)))
 449     (null rl)))
 450
 451 (defun recentf-elements (n)
 452   "Return a list of the first N elements of `recentf-list'."
 453   (let ((lh nil) (l recentf-list))
 454     (while (and l (> n 0))
 455       (setq lh (cons (car l) lh))
 456       (setq n (1- n))
 457       (setq l (cdr l)))
 458     (nreverse lh)))
 459
 460 (defun recentf-menu-elements (n)
 461   "Return a list of the first N menu elements from `recentf-list'.
 462 Each menu element has this form:
 463
 464  (MENU-ITEM . FILE-PATH)
 465
 466 MENU-ITEM is the menu item string displayed.
 467
 468 FILE-PATH is the path used to open the file when the corresponding MENU-ITEM
 469 is selected.
 470
 471 At the start each MENU-ITEM is set to its corresponding FILE-PATH."
 472   (mapcar '(lambda (item) (cons item item)) (recentf-elements n)))
 473
 474
 475 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 476 ;; Predefined menu filter functions ;;
 477 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 478
 479 (defun recentf-sort-ascending (l)
 480   "Sort the list of menu elements L in ascending order.
 481 The MENU-ITEM part of each menu element is compared."
 482   (sort l '(lambda (e1 e2) (string-lessp (car e1) (car e2)))))
 483
 484 (defun recentf-sort-descending (l)
 485   "Sort the list of menu elements L in descending order.
 486 The MENU-ITEM part of each menu element is compared."
 487   (sort l '(lambda (e1 e2) (string-lessp (car e2) (car e1)))))
 488
 489 (defun recentf-sort-basenames-ascending (l)
 490   "Sort the list of menu elements L in ascending order.
 491 Only file names (without directories) are compared."
 492   (sort l '(lambda (e1 e2) (string-lessp
 493                             (file-name-nondirectory (cdr e1))
 494                             (file-name-nondirectory (cdr e2))))))
 495
 496 (defun recentf-sort-basenames-descending (l)
 497   "Sort the list of menu elements L in descending order.
 498 Only file names (without directories) are compared."
 499   (sort l '(lambda (e1 e2) (string-lessp
 500                             (file-name-nondirectory (cdr e2))
 501                             (file-name-nondirectory (cdr e1))))))
 502
 503 (defun recentf-show-basenames (l)
 504   "Filter the list of menu elements L to show only file names (no directories)
 505 in the menu. When file names are duplicated their directory component is added."
 506   (let ((names  (mapcar '(lambda (item) (file-name-nondirectory (cdr item))) l))
 507         (dirs   (mapcar '(lambda (item) (file-name-directory (cdr item))) l))
 508         (pathes (mapcar 'cdr l))
 509         (pos    -1)
 510         item filtered-items filtered-list)
 511     (while names
 512       (setq item  (car names))
 513       (setq names (cdr names))
 514       (setq pos   (1+ pos))
 515       (setq filtered-list
 516             (cons (cons (if (or (member item names) (member item filtered-items))
 517                             (concat item " (" (nth pos dirs) ")")
 518                           item)
 519                         (nth pos pathes))
 520                   filtered-list))
 521       (setq filtered-items (cons item filtered-items)))
 522     (nreverse filtered-list)))
 523
 524 (defun recentf-show-basenames-ascending (l)
 525   "Filter the list of menu elements L to show only file names in the menu,
 526 sorted in ascending order. This filter combines the `recentf-sort-basenames-ascending'
 527 and `recentf-show-basenames' filters."
 528   (recentf-show-basenames (recentf-sort-basenames-ascending l)))
 529
 530 (defun recentf-show-basenames-descending (l)
 531   "Filter the list of menu elements L to show only file names in the menu,
 532 sorted in descending order. This filter combines the `recentf-sort-basenames-descending'
 533 and `recentf-show-basenames' filters."
 534   (recentf-show-basenames (recentf-sort-basenames-descending l)))
 535
 536 (defun recentf-relative-filter (l)
 537   "Filter the list of `recentf-menu-elements' L to show filenames
 538 relative to `default-directory'."
 539   (setq recentf-update-menu-p t)        ; force menu update
 540   (mapcar '(lambda (menu-element)
 541              (let* ((ful-path (cdr menu-element))
 542                     (rel-path (file-relative-name ful-path)))
 543                (if (string-match "^\\.\\." rel-path)
 544                    menu-element
 545                  (cons rel-path ful-path))))
 546           l))
 547
 548 (provide 'recentf)
 549
 550 (run-hooks 'recentf-load-hook)
 551
 552 ;;; recentf.el ends here.