lisp/recentf.el

   1 ;; recentf.el --- setup a menu of recently opened files
   2
   3 ;; Copyright (C) 1999 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 ;;; Code:
  29
  30 (require 'easymenu)
  31 (require 'widget)
  32 (eval-when-compile
  33   (require 'wid-edit))
  34
  35 (defconst recentf-save-file-header
  36   ";;; Automatically generated by `recentf' on %s.\n"
  37   "Header to be written into the `recentf-save-file'.")
  38
  39 (defvar recentf-list nil
  40   "List of recently opened files.")
  41
  42 (defvar recentf-update-menu-p t
  43   "Non-nil if the recentf menu must be updated.")
  44
  45 (defvar recentf-initialized-p nil
  46   "Non-nil if recentf already initialized.")
  47
  48 ;; IMPORTANT: This function must be defined before the following defcustoms
  49 ;; because it is used in their :set clause. To avoid byte-compiler warnings
  50 ;; the `symbol-value' function is used to access the `recentf-menu-path'
  51 ;; and `recentf-menu-title' values.
  52 (defun recentf-menu-customization-changed (sym val)
  53   "Function called when menu customization has changed.
  54 It removes the recentf menu and forces its complete redrawing."
  55   (when recentf-initialized-p
  56     (easy-menu-remove-item nil
  57                            (symbol-value 'recentf-menu-path)
  58                            (symbol-value 'recentf-menu-title))
  59     (setq recentf-update-menu-p t))
  60   (custom-set-default sym val))
  61
  62 (defgroup recentf nil
  63   "Maintain a menu of recently opened files."
  64   :version "21.1"
  65   :group 'files)
  66
  67 (defcustom recentf-max-saved-items 20
  68   "*Maximum number of items saved to `recentf-save-file'."
  69   :group 'recentf
  70   :type 'integer)
  71
  72 (defcustom recentf-save-file (expand-file-name "~/.recentf")
  73   "*File to save `recentf-list' into."
  74   :group 'recentf
  75   :type 'file)
  76
  77 (defcustom recentf-exclude nil
  78   "*List of regexps for filenames excluded from `recentf-list'."
  79   :group 'recentf
  80   :type '(repeat regexp))
  81
  82 (defcustom recentf-menu-title "Open Recent"
  83   "*Name of the recentf menu."
  84   :group 'recentf
  85   :type 'string
  86   :set 'recentf-menu-customization-changed)
  87
  88 (defcustom recentf-menu-path '("files")
  89   "*Path where to add the recentf menu.
  90 If nil add it at top-level (see also `easy-menu-change')."
  91   :group 'recentf
  92   :type '(choice (const :tag "Top Level" nil)
  93                  (sexp :tag "Menu Path"))
  94   :set 'recentf-menu-customization-changed)
  95
  96 (defcustom recentf-menu-before "open-file"
  97   "*Name of the menu before which the recentf menu will be added.
  98 If nil add it at end of menu (see also `easy-menu-change')."
  99   :group 'recentf
 100   :type '(choice (string :tag "Name")
 101                  (const :tag "Last" nil))
 102   :set 'recentf-menu-customization-changed)
 103
 104 (defcustom recentf-menu-action 'recentf-find-file
 105   "*Function to invoke with a filename item of the recentf menu.
 106 The default action `recentf-find-file' calls `find-file' to edit an
 107 existing file.  If the file does not exist or is not readable, it is
 108 not edited and its name is removed from `recentf-list'. You can use
 109 `find-file' instead to open non-existing files and keep them in the
 110 list of recently opened files."
 111   :group 'recentf
 112   :type 'function
 113   :set 'recentf-menu-customization-changed)
 114
 115 (defcustom recentf-max-menu-items 10
 116   "*Maximum number of items in the recentf menu."
 117   :group 'recentf
 118   :type 'integer
 119   :set 'recentf-menu-customization-changed)
 120
 121 (defcustom recentf-menu-filter nil
 122   "*Function used to filter files displayed in the recentf menu.
 123 Nil means no filter.  The following functions are predefined:
 124
 125 - - `recentf-sort-ascending' to sort menu items in ascending order.
 126 - - `recentf-sort-descending' to sort menu items in descending order.
 127
 128 The filter function is called with one argument, the list of filenames to be
 129 displayed in the menu and must return a new list of filenames."
 130   :group 'recentf
 131   :type 'function
 132   :set 'recentf-menu-customization-changed)
 133
 134 (defcustom recentf-menu-append-commands-p t
 135   "*If not-nil command items are appended to the menu."
 136   :group 'recentf
 137   :type 'boolean
 138   :set 'recentf-menu-customization-changed)
 139
 140 (defcustom recentf-keep-non-readable-files-p nil
 141   "*If nil (default), non-readable files are not kept in `recentf-list'."
 142   :group 'recentf
 143   :type 'boolean
 144   :require 'recentf
 145   :initialize 'custom-initialize-default
 146   :set  (lambda (sym val)
 147           (if val
 148               (remove-hook 'kill-buffer-hook 'recentf-remove-file-hook)
 149             (add-hook 'kill-buffer-hook 'recentf-remove-file-hook))
 150           (custom-set-default sym val)))
 151
 152 (defcustom recentf-mode nil
 153   "Toggle recentf mode.
 154 When recentf mode is enabled, it maintains a menu for visiting files that
 155 were operated on recently.
 156 Setting this variable directly does not take effect;
 157 use either \\[customize] or the function `recentf-mode'."
 158   :set (lambda (symbol value)
 159          (recentf-mode (or value 0)))
 160   :initialize 'custom-initialize-default
 161   :type 'boolean
 162   :group 'recentf
 163   :require 'recentf)
 164
 165 (defcustom recentf-load-hook nil
 166    "*Normal hook run at end of loading the `recentf' package."
 167   :group 'recentf
 168   :type 'hook)
 169
 170 ;;;###autoload
 171 (defun recentf-mode (&optional arg)
 172   "Toggle recentf mode.
 173 With prefix ARG, turn recentf mode on if and only if ARG is positive.
 174 Returns the new status of recentf mode (non-nil means on).
 175
 176 When recentf mode is enabled, it maintains a menu for visiting files that
 177 were operated on recently."
 178   (interactive "P")
 179   (let ((on-p (if arg
 180                   (> (prefix-numeric-value arg) 0)
 181                 (not recentf-mode))))
 182     (if on-p
 183         (unless recentf-initialized-p
 184           (setq recentf-initialized-p t)
 185           (if (file-readable-p recentf-save-file)
 186               (load-file recentf-save-file))
 187           (setq recentf-update-menu-p t)
 188           (add-hook 'find-file-hooks       'recentf-add-file-hook)
 189           (add-hook 'write-file-hooks      'recentf-add-file-hook)
 190           ;;    (add-hook 'activate-menubar-hook 'recentf-update-menu-hook)
 191           (add-hook 'menu-bar-update-hook  'recentf-update-menu-hook)
 192           (add-hook 'kill-emacs-hook       'recentf-save-list))
 193       (when recentf-initialized-p
 194         (setq recentf-initialized-p nil)
 195         (recentf-save-list)
 196         (easy-menu-remove-item nil recentf-menu-path recentf-menu-title)
 197         (remove-hook 'find-file-hooks       'recentf-add-file-hook)
 198         (remove-hook 'write-file-hooks      'recentf-add-file-hook)
 199         ;;    (remove-hook 'activate-menubar-hook 'recentf-update-menu-hook)
 200         (remove-hook 'menu-bar-update-hook  'recentf-update-menu-hook)
 201         (remove-hook 'kill-emacs-hook       'recentf-save-list)))
 202     (setq recentf-mode on-p)))
 203
 204 (defun recentf-add-file-hook ()
 205   "Insert the name of the file just opened or written into `recentf-list'."
 206   (and buffer-file-name (recentf-add-file buffer-file-name))
 207   nil)
 208
 209 (defun recentf-remove-file-hook ()
 210   "When a buffer is killed remove a non readable file from `recentf-list'."
 211   (and buffer-file-name (recentf-remove-if-non-readable buffer-file-name))
 212   nil)
 213
 214 (defun recentf-update-menu-hook ()
 215   "Update the recentf menu from the current `recentf-list'."
 216   (when recentf-update-menu-p
 217     (condition-case nil
 218         (progn
 219           (easy-menu-change recentf-menu-path
 220                             recentf-menu-title
 221                             (recentf-make-menu-items)
 222                             recentf-menu-before)
 223           (setq recentf-update-menu-p nil))
 224       (error nil))))
 225
 226 ;;;###autoload
 227 (defun recentf-save-list ()
 228   "Save the current `recentf-list' to the file `recentf-save-file'."
 229   (interactive)
 230   (let ((saved-list (recentf-elements recentf-max-saved-items)))
 231     (with-temp-buffer
 232       (erase-buffer)
 233       (insert (format recentf-save-file-header (current-time-string)))
 234       (insert "(setq recentf-list\n      '(\n")
 235       (mapcar '(lambda (e)
 236                  (insert (format "        %S\n" e)))
 237               saved-list)
 238       (insert "        ))")
 239       (if (file-writable-p recentf-save-file)
 240           (write-region (point-min) (point-max) recentf-save-file))
 241       (kill-buffer (current-buffer))))
 242   nil)
 243
 244 (defvar recentf-edit-selected-items nil
 245   "Used by `recentf-edit-list' to hold the list of files to be deleted
 246 from `recentf-list'.")
 247
 248 (defun recentf-edit-list-action (widget &rest ignore)
 249   "Checkbox widget action used by `recentf-edit-list' to select/unselect a file."
 250   (let ((value (widget-get widget ':tag)))
 251     ;; if value is already in the selected items
 252     (if (memq value recentf-edit-selected-items)
 253         ;; then remove it
 254         (progn
 255           (setq recentf-edit-selected-items
 256                 (delq value recentf-edit-selected-items))
 257           (message "%s removed from selection." value))
 258       ;; else add it
 259       (progn
 260         (setq recentf-edit-selected-items
 261               (nconc (list value) recentf-edit-selected-items))
 262         (message "%s added to selection." value)))))
 263
 264 ;;;###autoload
 265 (defun recentf-edit-list ()
 266   "Allow the user to edit the files that are kept in the recent list."
 267   (interactive)
 268   (with-current-buffer (get-buffer-create (concat "*" recentf-menu-title " - Edit list*"))
 269     (switch-to-buffer (current-buffer))
 270     (kill-all-local-variables)
 271     (let ((inhibit-read-only t))
 272       (erase-buffer))
 273     (let ((all (overlay-lists)))
 274       ;; Delete all the overlays.
 275       (mapcar 'delete-overlay (car all))
 276       (mapcar 'delete-overlay (cdr all)))
 277     (setq recentf-edit-selected-items nil)
 278     ;; Insert the dialog header
 279     (widget-insert "Select the files to be deleted from the 'recentf-list'.\n\n")
 280     (widget-insert "Click on Ok to update the list or on Cancel to quit.\n" )
 281     ;; Insert the list of files as checkboxes
 282     (mapcar '(lambda (item)
 283                (widget-create 'checkbox
 284                               :value nil ; unselected checkbox
 285                               :format "\n %[%v%]  %t"
 286                               :tag item
 287                               :notify 'recentf-edit-list-action))
 288             recentf-list)
 289     (widget-insert "\n\n")
 290     ;; Insert the Ok button
 291     (widget-create 'push-button
 292                    :notify (lambda (&rest ignore)
 293                              (if recentf-edit-selected-items
 294                                  (progn (kill-buffer (current-buffer))
 295                                         (mapcar '(lambda (item)
 296                                                    (setq recentf-list
 297                                                          (delq item recentf-list)))
 298                                                 recentf-edit-selected-items)
 299                                         (message "%S file(s) removed from the list"
 300                                                  (length recentf-edit-selected-items))
 301                                         (setq recentf-update-menu-p t))
 302                                (message "No file selected.")))
 303                    "Ok")
 304     (widget-insert " ")
 305     ;; Insert the Cancel button
 306     (widget-create 'push-button
 307                    :notify (lambda (&rest ignore)
 308                              (kill-buffer (current-buffer))
 309                              (message "Command canceled."))
 310                    "Cancel")
 311     (use-local-map widget-keymap)
 312     (widget-setup)))
 313
 314 ;;;###autoload
 315 (defun recentf-cleanup ()
 316   "Remove all non-readable and excluded files from `recentf-list'."
 317   (interactive)
 318   (setq recentf-list
 319         (delq nil
 320               (mapcar '(lambda (filename)
 321                          (and (file-readable-p filename)
 322                               (recentf-include-p filename)
 323                               filename))
 324                       recentf-list)))
 325   (setq recentf-update-menu-p t))
 326
 327 (defun recentf-open-more-files-action (widget &rest ignore)
 328   "Button widget action used by `recentf-open-more-files' to open a file."
 329   (kill-buffer (current-buffer))
 330   (funcall recentf-menu-action (widget-value widget)))
 331
 332 ;;;###autoload
 333 (defun recentf-open-more-files ()
 334   "Allow the user to open files that are not in the menu."
 335   (interactive)
 336   (with-current-buffer (get-buffer-create (concat "*" recentf-menu-title " - More*"))
 337     (switch-to-buffer (current-buffer))
 338     (kill-all-local-variables)
 339     (let ((inhibit-read-only t))
 340       (erase-buffer))
 341     (let ((all (overlay-lists)))
 342       ;; Delete all the overlays.
 343       (mapcar 'delete-overlay (car all))
 344       (mapcar 'delete-overlay (cdr all)))
 345     ;; Insert the dialog header
 346     (widget-insert "Click on a file to open it or on Cancel to quit.\n\n")
 347     ;; Insert the list of files as buttons
 348     (mapcar '(lambda (menu-element)
 349                (let ((menu-item (car menu-element))
 350                      (file-path (cdr menu-element)))
 351                  (widget-create 'push-button
 352                                 :button-face 'default
 353                                 :tag menu-item
 354                                 :help-echo (concat "Open " file-path)
 355                                 :format "%[%t%]"
 356                                 :notify 'recentf-open-more-files-action
 357                                 file-path)
 358                  (widget-insert "\n")))
 359             (funcall (or recentf-menu-filter 'identity)
 360                      (mapcar '(lambda (item) (cons item item))
 361                              (nthcdr recentf-max-menu-items recentf-list))))
 362     (widget-insert "\n")
 363     ;; Insert the Cancel button
 364     (widget-create 'push-button
 365                    :notify (lambda (&rest ignore)
 366                              (kill-buffer (current-buffer))
 367                              (message "Command canceled."))
 368                    "Cancel")
 369     (use-local-map widget-keymap)
 370     (widget-setup)))
 371
 372 (defvar recentf-menu-items-for-commands
 373   (list ["Cleanup list" recentf-cleanup t]
 374         ["Edit list..." recentf-edit-list t]
 375         ["Save list now" recentf-save-list t]
 376         (vector "Recentf Options..." '(customize-group "recentf") t))
 377   "List of menu items for recentf commands.")
 378
 379 (defun recentf-make-menu-items ()
 380   "Make menu items from `recentf-list'."
 381   (let ((file-items
 382          (mapcar '(lambda (entry)
 383                     (vector entry (list recentf-menu-action entry) t))
 384                  (funcall (or recentf-menu-filter 'identity)
 385                           (recentf-elements recentf-max-menu-items)))))
 386     (append (or file-items (list ["No files" t nil]))
 387             (and (< recentf-max-menu-items (length recentf-list))
 388                  (list ["More..." recentf-open-more-files t]))
 389             (and recentf-menu-append-commands-p
 390                  (cons ["---" nil nil]
 391                        recentf-menu-items-for-commands)))))
 392
 393 (defun recentf-add-file (filename)
 394   "Add or move FILENAME at the beginning of `recentf-list'.
 395 Does nothing if FILENAME matches one of the `recentf-exclude' regexps."
 396   (when (recentf-include-p filename)
 397     (setq recentf-list (cons filename (delete filename recentf-list)))
 398     (setq recentf-update-menu-p t)))
 399
 400 (defun recentf-remove-if-non-readable (filename)
 401   "Remove FILENAME from `recentf-list' if not readable."
 402   (unless (file-readable-p filename)
 403     (setq recentf-list (delete filename recentf-list))
 404     (setq recentf-update-menu-p t)))
 405
 406 (defun recentf-find-file (filename)
 407   "Edit file FILENAME using `find-file'.
 408 If FILENAME is not readable it is removed from `recentf-list'."
 409   (if (file-readable-p filename)
 410       (find-file filename)
 411     (progn
 412       (message "File `%s' not found." filename)
 413       (setq recentf-list (delete filename recentf-list))
 414       (setq recentf-update-menu-p t))))
 415
 416 (defun recentf-include-p (filename)
 417   "Return t if FILENAME matches none of the `recentf-exclude' regexps."
 418   (let ((rl recentf-exclude))
 419     (while (and rl (not (string-match (car rl) filename)))
 420       (setq rl (cdr rl)))
 421     (null rl)))
 422
 423 (defun recentf-elements (n)
 424   "Return a list of the first N elements of `recentf-list'."
 425   (let ((lh nil) (l recentf-list))
 426     (while (and l (> n 0))
 427       (setq lh (cons (car l) lh))
 428       (setq n (1- n))
 429       (setq l (cdr l)))
 430     (nreverse lh)))
 431
 432 (defun recentf-sort-ascending (l)
 433   "Sort the list of strings L in ascending order."
 434   (sort l '(lambda (e1 e2) (string-lessp e1 e2))))
 435
 436 (defun recentf-sort-descending (l)
 437   "Sort the list of strings L in descending order."
 438   (sort l '(lambda (e1 e2) (string-lessp e2 e1))))
 439
 440 (provide 'recentf)
 441
 442 (run-hooks 'recentf-load-hook)
 443
 444 ;;; recentf.el ends here.