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@dponce.com>
   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 (defgroup recentf-filters nil
  78   "Group to customize recentf menu filters.
  79 You should define the options of your own filters in this group."
  80   :group 'recentf)
  81
  82 (defcustom recentf-max-saved-items 20
  83   "*Maximum number of items saved to `recentf-save-file'."
  84   :group 'recentf
  85   :type 'integer)
  86
  87 (defcustom recentf-save-file (expand-file-name "~/.recentf")
  88   "*File to save `recentf-list' into."
  89   :group 'recentf
  90   :type 'file)
  91
  92 (defcustom recentf-exclude nil
  93   "*List of regexps for filenames excluded from `recentf-list'."
  94   :group 'recentf
  95   :type '(repeat regexp))
  96
  97 (defcustom recentf-menu-title "Open Recent"
  98   "*Name of the recentf menu."
  99   :group 'recentf
 100   :type 'string
 101   :set 'recentf-menu-customization-changed)
 102
 103 (defcustom recentf-menu-path '("files")
 104   "*Path where to add the recentf menu.
 105 If nil add it at top-level (see also `easy-menu-change')."
 106   :group 'recentf
 107   :type '(choice (const :tag "Top Level" nil)
 108                  (sexp :tag "Menu Path"))
 109   :set 'recentf-menu-customization-changed)
 110
 111 (defcustom recentf-menu-before "open-file"
 112   "*Name of the menu before which the recentf menu will be added.
 113 If nil add it at end of menu (see also `easy-menu-change')."
 114   :group 'recentf
 115   :type '(choice (string :tag "Name")
 116                  (const :tag "Last" nil))
 117   :set 'recentf-menu-customization-changed)
 118
 119 (defcustom recentf-menu-action 'recentf-find-file
 120   "*Function to invoke with a filename item of the recentf menu.
 121 The default action `recentf-find-file' calls `find-file' to edit an
 122 existing file.  If the file does not exist or is not readable, it is
 123 not edited and its name is removed from `recentf-list'. You can use
 124 `find-file' instead to open non-existing files and keep them in the
 125 list of recently opened files."
 126   :group 'recentf
 127   :type 'function
 128   :set 'recentf-menu-customization-changed)
 129
 130 (defcustom recentf-max-menu-items 10
 131   "*Maximum number of items in the recentf menu."
 132   :group 'recentf
 133   :type 'integer
 134   :set 'recentf-menu-customization-changed)
 135
 136 (defcustom recentf-menu-filter nil
 137   "*Function used to filter files displayed in the recentf menu.
 138 Nil means no filter.  The following functions are predefined:
 139
 140 - - `recentf-sort-ascending' to sort menu items in ascending order.
 141 - - `recentf-sort-descending' to sort menu items in descending order.
 142 - - `recentf-sort-basenames-ascending' to sort file names in descending order.
 143 - - `recentf-sort-basenames-descending' to sort file names in descending order.
 144 - - `recentf-sort-directories-ascending' to sort directories in ascending order.
 145 - - `recentf-sort-directories-descending' to sort directories in descending order.
 146 - - `recentf-show-basenames' to show file names (no directories) in menu items.
 147 - - `recentf-show-basenames-ascending' to show file names in ascending order.
 148 - - `recentf-show-basenames-descending' to show file names in descending order.
 149 - - `recentf-relative-filter' to show file names relative to `default-directory'.
 150 - - `recentf-arrange-by-rule' to show sub-menus following user defined rules.
 151 - - `recentf-arrange-by-mode' to show a sub-menu for each major mode.
 152 - - `recentf-arrange-by-dir' to show a sub-menu for each directory.
 153 - - `recentf-filter-changer' to manage a ring of filters.
 154
 155 The filter function is called with one argument, the list of menu elements
 156 used to build the menu and must return a new list of menu elements (see
 157 `recentf-make-menu-element' for menu element form)."
 158   :group 'recentf
 159   :type 'function
 160   :set 'recentf-menu-customization-changed)
 161
 162 (defcustom recentf-menu-append-commands-p t
 163   "*If not-nil command items are appended to the menu."
 164   :group 'recentf
 165   :type 'boolean
 166   :set 'recentf-menu-customization-changed)
 167
 168 (defcustom recentf-keep-non-readable-files-p nil
 169   "*If nil (default), non-readable files are not kept in `recentf-list'."
 170   :group 'recentf
 171   :type 'boolean
 172   :require 'recentf
 173   :initialize 'custom-initialize-default
 174   :set (lambda (sym val)
 175          (if val
 176              (remove-hook 'kill-buffer-hook 'recentf-remove-file-hook)
 177            (add-hook 'kill-buffer-hook 'recentf-remove-file-hook))
 178          (custom-set-default sym val)))
 179
 180 (defcustom recentf-mode nil
 181   "Toggle recentf mode.
 182 When recentf mode is enabled, it maintains a menu for visiting files that
 183 were operated on recently.
 184 Setting this variable directly does not take effect;
 185 use either \\[customize] or the function `recentf-mode'."
 186   :set (lambda (symbol value)
 187          (recentf-mode (or value 0)))
 188   :initialize 'custom-initialize-default
 189   :type 'boolean
 190   :group 'recentf
 191   :require 'recentf)
 192
 193 (defcustom recentf-load-hook nil
 194    "*Normal hook run at end of loading the `recentf' package."
 195   :group 'recentf
 196   :type 'hook)
 197
 198 ;;;
 199 ;;; Common functions
 200 ;;;
 201 (defconst recentf-case-fold-search
 202   (memq system-type '(vax-vms windows-nt))
 203   "Non-nil if recentf searches and matches should ignore case.")
 204
 205 (defun recentf-include-p (filename)
 206   "Return t if FILENAME matches none of the `recentf-exclude' regexps."
 207   (let ((case-fold-search recentf-case-fold-search)
 208         (rl recentf-exclude))
 209     (while (and rl (not (string-match (car rl) filename)))
 210       (setq rl (cdr rl)))
 211     (null rl)))
 212
 213 (defun recentf-add-file (filename)
 214   "Add or move FILENAME at the beginning of `recentf-list'.
 215 Does nothing if FILENAME matches one of the `recentf-exclude' regexps."
 216   (let ((filename (expand-file-name filename)))
 217     (when (recentf-include-p filename)
 218       (setq recentf-list (cons filename (delete filename recentf-list)))
 219       (setq recentf-update-menu-p t))))
 220
 221 (defun recentf-remove-if-non-readable (filename)
 222   "Remove FILENAME from `recentf-list' if not readable."
 223   (unless (file-readable-p filename)
 224     (setq recentf-list (delete filename recentf-list))
 225     (setq recentf-update-menu-p t)))
 226
 227 (defun recentf-find-file (filename)
 228   "Edit file FILENAME using `find-file'.
 229 If FILENAME is not readable it is removed from `recentf-list'."
 230   (if (file-readable-p filename)
 231       (find-file filename)
 232     (progn
 233       (message "File `%s' not found." filename)
 234       (setq recentf-list (delete filename recentf-list))
 235       (setq recentf-update-menu-p t))))
 236
 237 (defun recentf-trunc-list (l n)
 238   "Return a list of the first N elements of L."
 239   (let ((lh nil))
 240     (while (and l (> n 0))
 241       (setq lh (cons (car l) lh))
 242       (setq n (1- n))
 243       (setq l (cdr l)))
 244     (nreverse lh)))
 245
 246 (defun recentf-elements (n)
 247   "Return a list of the first N elements of `recentf-list'."
 248   (recentf-trunc-list recentf-list n))
 249
 250 (defun recentf-make-menu-element (menu-item menu-value)
 251   "Create a new menu-element.
 252
 253 A menu element is a pair (MENU-ITEM . MENU-VALUE) where:
 254
 255 - - MENU-ITEM  is the menu item string displayed.
 256 - - MENU-VALUE is the path used to open the file when the
 257                corresponding MENU-ITEM is selected. Or it is
 258                a pair (SUB-MENU-TITLE . MENU-ELEMENTS) where
 259                SUB-MENU-TITLE is a sub-menu title and
 260                MENU-ELEMENTS is the list of menu elements in
 261                the sub-menu."
 262   (cons menu-item menu-value))
 263
 264 (defun recentf-menu-element-item (e)
 265   "Return the item part of the menu-element E."
 266   (car e))
 267
 268 (defun recentf-menu-element-value (e)
 269   "Return the value part of the menu-element E."
 270   (cdr e))
 271
 272 (defun recentf-set-menu-element-item (e item)
 273   "Change the item part of menu-element E to ITEM."
 274   (setcar e item))
 275
 276 (defun recentf-set-menu-element-value (e value)
 277   "Change the value part of menu-element E to VALUE."
 278   (setcdr e value))
 279
 280 (defun recentf-sub-menu-element-p (e)
 281   "Return non-nil if menu-element E defines a sub-menu."
 282   (consp (recentf-menu-element-value e)))
 283
 284 (defun recentf-make-default-menu-element (file-path)
 285   "Make a new default menu element (MENU-ITEM . MENU-VALUE) for the
 286 given recent file path FILE-PATH. MENU-ITEM and MENU-VALUE are set to
 287 FILE-PATH. See also `recentf-make-menu-element'."
 288   (recentf-make-menu-element file-path file-path))
 289
 290 (defun recentf-menu-elements (n)
 291   "Return a list of the first N default menu elements from
 292 `recentf-list'. See also `recentf-make-default-menu-element'."
 293   (mapcar 'recentf-make-default-menu-element
 294           (recentf-elements n)))
 295
 296 (defun recentf-apply-menu-filter (filter l)
 297   "Convenient funtion to apply the function FILTER to the list of
 298 menu-elements L. It takes care of sub-menu elements in L and
 299 recursively apply FILTER to them. It is guarantee than FILTER receives
 300 only a list of single menu-elements (no sub-menu)."
 301   (if (and (functionp filter) l)
 302       (let ((case-fold-search recentf-case-fold-search)
 303             menu-element sub-menu-elements single-elements)
 304         ;; split L in two sub-listes:
 305         ;;   one of sub-menus elements and
 306         ;;   one of single menu elements
 307         (while l
 308           (setq menu-element (car l))
 309           (if (recentf-sub-menu-element-p menu-element)
 310               (setq sub-menu-elements
 311                     (cons menu-element sub-menu-elements))
 312             (setq single-elements
 313                   (cons menu-element single-elements)))
 314           (setq l (cdr l)))
 315         ;; apply FILTER to the list of single menu elements
 316         (if single-elements
 317             (setq single-elements (funcall filter
 318                                            (nreverse single-elements))))
 319         ;; apply FILTER to sub-menu menu element list
 320         (setq l sub-menu-elements)
 321         (setq sub-menu-elements nil)
 322         (while l
 323           (setq menu-element (car l))
 324           (recentf-set-menu-element-value
 325            menu-element
 326            (recentf-apply-menu-filter
 327             filter
 328             (recentf-menu-element-value menu-element)))
 329           (setq sub-menu-elements (cons menu-element sub-menu-elements))
 330           (setq l (cdr l)))
 331         ;; build and return the new filtered menu element list
 332         (nconc sub-menu-elements single-elements))
 333     l))
 334
 335 (defvar recentf-menu-items-for-commands
 336   (list ["Cleanup list" recentf-cleanup t]
 337         ["Edit list..." recentf-edit-list t]
 338         ["Save list now" recentf-save-list t]
 339         (vector "Recentf Options..." '(customize-group "recentf") t))
 340   "List of menu items for recentf commands.")
 341
 342 (defvar recentf-menu-filter-commands nil
 343   "This variable can be used by menu filters to setup their own command menu.
 344
 345 If non-nil it must contain a list of valid menu-items to be appended
 346 to the recent file list part of the menu.  Before calling a menu
 347 filter function this variable is reset to nil.")
 348
 349 (defun recentf-make-menu-items ()
 350   "Make menu items from `recentf-list'."
 351   (setq recentf-menu-filter-commands nil)
 352   (let ((file-items
 353          (mapcar 'recentf-make-menu-item
 354                  (recentf-apply-menu-filter
 355                   recentf-menu-filter
 356                   (recentf-menu-elements recentf-max-menu-items)))))
 357     (append (or file-items (list ["No files" t nil]))
 358             (and (< recentf-max-menu-items (length recentf-list))
 359                  (list ["More..." recentf-open-more-files t]))
 360             (and recentf-menu-filter-commands
 361                  (cons "---"
 362                        recentf-menu-filter-commands))
 363             (and recentf-menu-append-commands-p
 364                  (cons "---"
 365                        recentf-menu-items-for-commands)))))
 366
 367 (defun recentf-make-menu-item (menu-element)
 368   "Make a menu item from a menu element (see `recentf-make-menu-element')."
 369   (let ((menu-item  (recentf-menu-element-item  menu-element))
 370         (menu-value (recentf-menu-element-value menu-element)))
 371     (if (recentf-sub-menu-element-p menu-element)
 372         (cons menu-item (mapcar 'recentf-make-menu-item menu-value))
 373       (vector menu-item
 374               (list recentf-menu-action menu-value)
 375               t))))
 376
 377 ;;;
 378 ;;; Predefined menu filter functions
 379 ;;;
 380
 381 (defun recentf-sort-ascending (l)
 382   "Sort the list of menu elements L in ascending order.
 383 The MENU-ITEM part of each menu element is compared."
 384   (sort (copy-sequence l)
 385         (function
 386          (lambda (e1 e2)
 387            (string-lessp (recentf-menu-element-item e1)
 388                          (recentf-menu-element-item e2))))))
 389
 390 (defun recentf-sort-descending (l)
 391   "Sort the list of menu elements L in descending order.
 392 The MENU-ITEM part of each menu element is compared."
 393   (sort (copy-sequence l)
 394         (function
 395          (lambda (e1 e2)
 396            (string-lessp (recentf-menu-element-item e2)
 397                          (recentf-menu-element-item e1))))))
 398
 399 (defun recentf-sort-basenames-ascending (l)
 400   "Sort the list of menu elements L in ascending order.
 401 Only file names (without directories) are compared."
 402   (sort (copy-sequence l)
 403         (function
 404          (lambda (e1 e2)
 405            (string-lessp
 406             (file-name-nondirectory (recentf-menu-element-value e1))
 407             (file-name-nondirectory (recentf-menu-element-value e2)))))))
 408
 409 (defun recentf-sort-basenames-descending (l)
 410   "Sort the list of menu elements L in descending order.
 411 Only file names (without directories) are compared."
 412   (sort (copy-sequence l)
 413         (function
 414          (lambda (e1 e2)
 415            (string-lessp
 416             (file-name-nondirectory (recentf-menu-element-value e2))
 417             (file-name-nondirectory (recentf-menu-element-value e1)))))))
 418
 419 (defun recentf-directory-compare (p1 p2)
 420   "Compare directories then filenames in pathes P1 and P2 and return
 421 non-nil if P1 is less than P2."
 422   (let ((d1 (file-name-directory    p1))
 423         (f1 (file-name-nondirectory p1))
 424         (d2 (file-name-directory    p2))
 425         (f2 (file-name-nondirectory p2)))
 426     (if (string= d1 d2)
 427         (string-lessp f1 f2)
 428       (string-lessp d1 d2))))
 429
 430 (defun recentf-sort-directories-ascending (l)
 431   "Sort the list of menu elements L in ascending order.
 432 Compares directories then filenames to order the list."
 433   (sort (copy-sequence l)
 434         (function
 435          (lambda (e1 e2)
 436            (recentf-directory-compare (recentf-menu-element-value e1)
 437                                       (recentf-menu-element-value e2))))))
 438
 439 (defun recentf-sort-directories-descending (l)
 440   "Sort the list of menu elements L in descending order.
 441 Compares directories then filenames to order the list."
 442   (sort (copy-sequence l)
 443         (function
 444          (lambda (e1 e2)
 445            (recentf-directory-compare (recentf-menu-element-value e2)
 446                                       (recentf-menu-element-value e1))))))
 447
 448 (defun recentf-show-basenames (l)
 449   "Filter the list of menu elements L to show only file names (no directories)
 450 in the menu. When file names are duplicated their directory component is added."
 451   (let ((names  (mapcar (function
 452                          (lambda (item)
 453                            (file-name-nondirectory
 454                             (recentf-menu-element-value item))))
 455                         l))
 456         (dirs   (mapcar (function
 457                          (lambda (item)
 458                            (file-name-directory
 459                             (recentf-menu-element-value item))))
 460                         l))
 461         (pathes (mapcar 'recentf-menu-element-value l))
 462         (pos    -1)
 463         item filtered-items filtered-list)
 464     (while names
 465       (setq item  (car names))
 466       (setq names (cdr names))
 467       (setq pos   (1+ pos))
 468       (setq filtered-list
 469             (cons (recentf-make-menu-element
 470                    (if (or (member item names) (member item filtered-items))
 471                        (concat item " (" (nth pos dirs) ")")
 472                      item)
 473                    (nth pos pathes))
 474                   filtered-list))
 475       (setq filtered-items (cons item filtered-items)))
 476     (nreverse filtered-list)))
 477
 478 (defun recentf-show-basenames-ascending (l)
 479   "Filter the list of menu elements L to show only file names in the menu,
 480 sorted in ascending order. This filter combines the `recentf-sort-basenames-ascending'
 481 and `recentf-show-basenames' filters."
 482   (recentf-show-basenames (recentf-sort-basenames-ascending l)))
 483
 484 (defun recentf-show-basenames-descending (l)
 485   "Filter the list of menu elements L to show only file names in the menu,
 486 sorted in descending order. This filter combines the `recentf-sort-basenames-descending'
 487 and `recentf-show-basenames' filters."
 488   (recentf-show-basenames (recentf-sort-basenames-descending l)))
 489
 490 (defun recentf-relative-filter (l)
 491   "Filter the list of `recentf-menu-elements' L to show filenames
 492 relative to `default-directory'."
 493   (setq recentf-update-menu-p t)        ; force menu update
 494   (mapcar (function
 495            (lambda (menu-element)
 496              (let* ((ful-path (recentf-menu-element-value menu-element))
 497                     (rel-path (file-relative-name ful-path)))
 498                (if (string-match "^\\.\\." rel-path)
 499                    menu-element
 500                  (recentf-make-menu-element rel-path ful-path)))))
 501           l))
 502
 503 (defcustom recentf-arrange-rules
 504   '(
 505     ("Elisp files (%d)" ".\\.el$")
 506     ("Java files (%d)"  ".\\.java$")
 507     ("C/C++ files (%d)" "c\\(pp\\)?$")
 508     )
 509   "*List of rules used by `recentf-arrange-by-rule' to build sub-menus.
 510 A rule is a pair (SUB-MENU-TITLE . MATCHER). SUB-MENU-TITLE is the
 511 displayed title of the sub-menu where a '%d' `format' pattern is
 512 replaced by the number of items in the sub-menu. MATCHER is a regexp
 513 or a list of regexps. Items matching one of the regular expressions in
 514 MATCHER are added to the corresponding sub-menu."
 515   :group 'recentf-filters
 516   :type '(repeat (cons string (repeat regexp)))
 517   :set 'recentf-menu-customization-changed)
 518
 519 (defcustom recentf-arrange-by-rule-others "Other files (%d)"
 520   "*Title of the `recentf-arrange-by-rule' sub-menu where items that
 521 don't match any `recentf-arrange-rules' are displayed. If nil
 522 these items are displayed in the main recent files menu. A '%d'
 523 `format' pattern in the title is replaced by the number of items in
 524 the sub-menu."
 525   :group 'recentf-filters
 526   :type '(choice (const  :tag "Main menu" nil)
 527                  (string :tag "Title"))
 528   :set 'recentf-menu-customization-changed)
 529
 530 (defcustom recentf-arrange-by-rules-min-items 0
 531   "*Minimum number of items in a `recentf-arrange-by-rule' sub-menu.
 532 If the number of items in a sub-menu is less than this value the
 533 corresponding sub-menu items are displayed in the main recent files
 534 menu or in the `recentf-arrange-by-rule-others' sub-menu if
 535 defined."
 536   :group 'recentf-filters
 537   :type 'number
 538   :set 'recentf-menu-customization-changed)
 539
 540 (defcustom recentf-arrange-by-rule-subfilter nil
 541   "*Function used by `recentf-arrange-by-rule' to filter sub-menu elements.
 542 Nil means no filter. See also `recentf-menu-filter'. You can't use
 543 `recentf-arrange-by-rule' itself here!"
 544   :group 'recentf-filters
 545   :type 'function
 546   :set (lambda (sym val)
 547          (if (eq val 'recentf-arrange-by-rule)
 548              (error "Can't use `recentf-arrange-by-rule' itself here!")
 549            (recentf-menu-customization-changed sym val))))
 550
 551 (defun recentf-match-rule-p (matcher file-path)
 552   "Return non-nil if FILE-PATH match the rule specified by MATCHER.
 553 See `recentf-arrange-rules' for details on MATCHER."
 554   (if (stringp matcher)
 555       (string-match matcher file-path)
 556     (while (and (consp matcher)
 557                 (not (string-match (car matcher) file-path)))
 558       (setq matcher (cdr matcher)))
 559     matcher))
 560
 561 (defun recentf-arrange-by-rule (l)
 562   "Filter the list of menu-elements L to arrange them in sub-menus
 563 following rules in `recentf-arrange-rules'."
 564   (let ((sub-menus-number (length recentf-arrange-rules)))
 565     (if (> sub-menus-number 0)
 566         (let ((sub-menus (apply 'vector
 567                                 (mapcar (function
 568                                          (lambda (pair)
 569                                            (list (car pair))))
 570                                         recentf-arrange-rules)))
 571               other-menu-elements index min-size)
 572           (while l
 573             (let* ((menu-element (car l))
 574                    (file-path    (recentf-menu-element-value menu-element))
 575                    (rules        recentf-arrange-rules)
 576                    (found        nil))
 577               (setq index 0)
 578               (while (and (not found) rules)
 579                 (if (recentf-match-rule-p (cdar rules) file-path)
 580                     (let ((sub-menu (aref sub-menus index)))
 581                       (setq found t)
 582                       (recentf-set-menu-element-value
 583                        sub-menu
 584                        (cons menu-element (recentf-menu-element-value sub-menu)))
 585                       ))
 586                 (setq index (1+  index))
 587                 (setq rules (cdr rules)))
 588               (or found
 589                   (setq other-menu-elements
 590                         (cons menu-element other-menu-elements)))
 591               (setq l (cdr l))))
 592           (setq index    0)
 593           (setq l        nil)
 594           (setq min-size (if (integerp recentf-arrange-by-rules-min-items)
 595                              (max 0 recentf-arrange-by-rules-min-items)
 596                            0))
 597           (while (< index sub-menus-number)
 598             (let* ((sub-menu          (aref sub-menus index))
 599                    (sub-menu-title    (recentf-menu-element-item  sub-menu))
 600                    (sub-menu-elements (recentf-menu-element-value sub-menu))
 601                    (sub-menu-length   (length sub-menu-elements)))
 602               (if (> sub-menu-length 0)
 603                   (cond
 604                    ((< sub-menu-length min-size)
 605                     (setq other-menu-elements
 606                           (nconc sub-menu-elements other-menu-elements)))
 607                    ((>= sub-menu-length min-size)
 608                     (recentf-set-menu-element-item
 609                      sub-menu
 610                      (format sub-menu-title sub-menu-length))
 611                     (recentf-set-menu-element-value
 612                      sub-menu
 613                      (recentf-apply-menu-filter
 614                       recentf-arrange-by-rule-subfilter
 615                       (nreverse sub-menu-elements)))
 616                     (setq   l (cons sub-menu l)))))
 617               (setq index (1+ index))))
 618           (if (and (stringp recentf-arrange-by-rule-others)
 619                    other-menu-elements)
 620               (setq l
 621                     (nreverse
 622                      (cons (recentf-make-menu-element
 623                             (format recentf-arrange-by-rule-others
 624                                     (length other-menu-elements))
 625                             (recentf-apply-menu-filter
 626                              recentf-arrange-by-rule-subfilter
 627                              (nreverse other-menu-elements)))
 628                            l)))
 629             (setq l (nconc (nreverse l)
 630                            (recentf-apply-menu-filter
 631                             recentf-arrange-by-rule-subfilter
 632                             (nreverse other-menu-elements)))))))
 633     l))
 634
 635 (defun recentf-build-mode-rules ()
 636   "Convert `auto-mode-alist' to `recentf-arrange-rules' format."
 637   (let ((case-fold-search recentf-case-fold-search)
 638         (modes auto-mode-alist)
 639         regexp mode rule-name rule rules)
 640     (while modes
 641       (setq regexp (caar modes))
 642       (setq mode   (cdar modes))
 643       (when (symbolp mode)
 644         (setq rule-name (symbol-name mode))
 645         (if (string-match "\\(.*\\)-mode$" rule-name)
 646             (setq rule-name (match-string 1 rule-name)))
 647         (setq rule-name (concat rule-name " (%d)"))
 648         (setq rule (assoc rule-name rules))
 649         (if rule
 650             (setcdr rule (cons regexp (cdr rule)))
 651           (setq rules (cons (list rule-name regexp) rules))))
 652       (setq modes (cdr modes)))
 653     ;; It is important to preserve auto-mode-alist order
 654     ;; to ensure the right file <-> mode association
 655     (nreverse rules)))
 656
 657 (defun recentf-arrange-by-mode (l)
 658   "Filter the list of menu-elements L to build sub-menus for each
 659 major mode."
 660   (let ((recentf-arrange-rules (recentf-build-mode-rules))
 661         (recentf-arrange-by-rule-others "others (%d)"))
 662     (recentf-arrange-by-rule l)))
 663
 664 (defun recentf-build-dir-rules (l)
 665   "Convert directories in the list of menu-elements L to rules in
 666 `recentf-arrange-rules' format."
 667   (let (dirs)
 668     (mapcar (function
 669              (lambda (e)
 670                (let ((dir (file-name-directory
 671                            (recentf-menu-element-value e))))
 672                  (or (member dir dirs)
 673                      (setq dirs (cons dir dirs))))))
 674             l)
 675     (mapcar (function
 676              (lambda (d)
 677                (cons (concat d " (%d)")
 678                      (concat "\\`" d))))
 679             (nreverse (sort dirs 'string-lessp)))))
 680
 681 (defun recentf-file-name-nondir (l)
 682   "Filter the list of menu-elements L to show only filenames. This
 683 simplified version of `recentf-show-basenames' do not handle
 684 duplicates. It is used by `recentf-arrange-by-dir' as its
 685 `recentf-arrange-by-rule-subfilter'."
 686   (mapcar (function
 687            (lambda (e)
 688              (recentf-make-menu-element
 689               (file-name-nondirectory (recentf-menu-element-value e))
 690               (recentf-menu-element-value e))))
 691           l))
 692
 693 (defun recentf-arrange-by-dir (l)
 694   "Filter the list of menu-elements L to build sub-menus for each
 695 directory."
 696   (let ((recentf-arrange-rules (recentf-build-dir-rules l))
 697         (recentf-arrange-by-rule-subfilter 'recentf-file-name-nondir)
 698         recentf-arrange-by-rule-others)
 699     (nreverse (recentf-arrange-by-rule l))))
 700
 701 (defvar recentf-filter-changer-state nil
 702   "Used by `recentf-filter-changer' to hold its state.")
 703
 704 (defcustom recentf-filter-changer-alist
 705   '(
 706     (recentf-arrange-by-mode . "*Files by Mode*")
 707     (recentf-arrange-by-dir  . "*Files by Directory*")
 708     (recentf-arrange-by-rule . "*Files by User Rule*")
 709     )
 710   "*List of filters managed by `recentf-filter-changer'.
 711 Each filter is defined by a pair (FILTER-FUN . FILTER-LBL) where:
 712
 713 - - FILTER-FUN is the function that filters menu-elements
 714 - - FILTER-LBL is the menu item used to activate the filter"
 715   :group 'recentf-filters
 716   :type '(repeat (cons function string))
 717   :set (lambda (sym val)
 718          (setq recentf-filter-changer-state nil)
 719          (recentf-menu-customization-changed sym val)))
 720
 721 (defun recentf-filter-changer-goto-next ()
 722   "Go to the next filter available (see `recentf-filter-changer')."
 723   (and (consp recentf-filter-changer-state)
 724        (setq recentf-filter-changer-state
 725              (cdr recentf-filter-changer-state)))
 726   (setq recentf-update-menu-p t))
 727
 728 (defun recentf-filter-changer-get-current ()
 729   "Get the current filter available (see `recentf-filter-changer')."
 730   (if (null recentf-filter-changer-state)
 731       (setq recentf-filter-changer-state recentf-filter-changer-alist))
 732   (and (consp recentf-filter-changer-state)
 733        (car recentf-filter-changer-state)))
 734
 735 (defun recentf-filter-changer-get-next ()
 736   "Get the next filter available (see `recentf-filter-changer')."
 737   (let ((filters recentf-filter-changer-state))
 738     (cond ((consp filters)
 739            (setq filters (cdr filters))
 740            (if (null filters)
 741                (setq filters recentf-filter-changer-alist)))
 742           (t
 743            (setq filters recentf-filter-changer-alist)
 744            (if (consp filters)
 745                (setq filters (cdr filters)))))
 746     (if (consp filters)
 747         (car filters))))
 748
 749 (defun recentf-filter-changer (l)
 750   "Manage a ring of filters. `recentf-filter-changer-alist' defines
 751 the filters in the ring. Actual filtering of L is delegated to the
 752 current filter in the ring. A filter menu item is displayed allowing
 753 to dynamically activate the next filter in the ring. If the filter
 754 ring is empty L is left unchanged."
 755   (let ((current-filter-item (recentf-filter-changer-get-current))
 756         (next-filter-item    (recentf-filter-changer-get-next)))
 757     (when current-filter-item
 758       (setq l (recentf-apply-menu-filter (car current-filter-item) l))
 759       (if next-filter-item
 760           (setq recentf-menu-filter-commands
 761                 (list (vector (cdr next-filter-item)
 762                               '(recentf-filter-changer-goto-next)
 763                               t)))))
 764     l))
 765
 766 ;;;
 767 ;;; Dialogs stuff
 768 ;;;
 769
 770 (defun recentf-cancel-dialog (&rest ignore)
 771   "Cancel the current dialog. Used by `recentf-edit-list' and
 772 `recentf-open-files' dialogs."
 773   (interactive)
 774   (kill-buffer (current-buffer))
 775   (message "Dialog canceled."))
 776
 777 (defvar recentf-dialog-mode-map nil
 778   "`recentf-dialog-mode' keymap.")
 779
 780 (if recentf-dialog-mode-map
 781     ()
 782   (setq recentf-dialog-mode-map (make-sparse-keymap))
 783   (define-key recentf-dialog-mode-map "q" 'recentf-cancel-dialog)
 784   (define-key recentf-dialog-mode-map [down-mouse-1] 'widget-button-click)
 785   (set-keymap-parent recentf-dialog-mode-map widget-keymap))
 786
 787 (defun recentf-dialog-mode ()
 788   "Major mode used in recentf dialogs.
 789
 790 These are the special commands of recentf-dialog-mode mode:
 791     q -- cancel this dialog."
 792   (interactive)
 793   (setq major-mode 'recentf-dialog-mode)
 794   (setq mode-name "recentf-dialog")
 795   (use-local-map recentf-dialog-mode-map))
 796
 797 ;;;
 798 ;;; Hooks and Commands
 799 ;;;
 800
 801 (defun recentf-add-file-hook ()
 802   "Insert the name of the file just opened or written into `recentf-list'."
 803   (and buffer-file-name (recentf-add-file buffer-file-name))
 804   nil)
 805
 806 (defun recentf-remove-file-hook ()
 807   "When a buffer is killed remove a non readable file from `recentf-list'."
 808   (and buffer-file-name (recentf-remove-if-non-readable buffer-file-name))
 809   nil)
 810
 811 (defun recentf-update-menu-hook ()
 812   "Update the recentf menu from the current `recentf-list'."
 813   (when recentf-update-menu-p
 814     (condition-case nil
 815         (progn
 816           (setq recentf-update-menu-p nil)
 817           (easy-menu-change recentf-menu-path
 818                             recentf-menu-title
 819                             (recentf-make-menu-items)
 820                             recentf-menu-before))
 821       (error nil))))
 822
 823 (defun recentf-dump-variable (variable &optional limit)
 824   "Insert a \"(setq VARIABLE value)\" in the current buffer. Optional
 825 argument LIMIT specifies a maximum length when VARIABLE value is a
 826 list (default to the full list)."
 827   (let ((value (symbol-value variable)))
 828     (insert (format "(setq %S\n      '(\n" variable))
 829     (cond ((consp value)
 830            (if (and (integerp limit) (> limit 0))
 831                (setq value (recentf-trunc-list value limit)))
 832            (mapcar (function
 833                     (lambda (e)
 834                       (insert (format "        %S\n" e))))
 835                    value))
 836           (t
 837            (insert (format "        %S\n" value))))
 838     (insert "        ))\n")
 839     ))
 840
 841 ;;;###autoload
 842 (defun recentf-save-list ()
 843   "Save the current `recentf-list' to the file `recentf-save-file'."
 844   (interactive)
 845   (with-temp-buffer
 846     (erase-buffer)
 847     (insert (format recentf-save-file-header (current-time-string)))
 848     (recentf-dump-variable 'recentf-list recentf-max-saved-items)
 849     (recentf-dump-variable 'recentf-filter-changer-state)
 850     (if (file-writable-p recentf-save-file)
 851         (write-region (point-min) (point-max) recentf-save-file))
 852     (kill-buffer (current-buffer)))
 853   nil)
 854
 855 (defvar recentf-edit-selected-items nil
 856   "Used by `recentf-edit-list' to hold the list of files to be deleted
 857 from `recentf-list'.")
 858
 859 (defun recentf-edit-list-action (widget &rest ignore)
 860   "Checkbox widget action used by `recentf-edit-list' to select/unselect a file."
 861   (let ((value (widget-get widget ':tag)))
 862     ;; if value is already in the selected items
 863     (if (memq value recentf-edit-selected-items)
 864         ;; then remove it
 865         (progn
 866           (setq recentf-edit-selected-items
 867                 (delq value recentf-edit-selected-items))
 868           (message "%s removed from selection." value))
 869       ;; else add it
 870       (progn
 871         (setq recentf-edit-selected-items
 872               (nconc (list value) recentf-edit-selected-items))
 873         (message "%s added to selection." value)))))
 874
 875 ;;;###autoload
 876 (defun recentf-edit-list ()
 877   "Allow the user to edit the files that are kept in the recent list."
 878   (interactive)
 879   (with-current-buffer (get-buffer-create (concat "*" recentf-menu-title " - Edit list*"))
 880     (switch-to-buffer (current-buffer))
 881     (kill-all-local-variables)
 882     (let ((inhibit-read-only t))
 883       (erase-buffer))
 884     (let ((all (overlay-lists)))
 885       ;; Delete all the overlays.
 886       (mapcar 'delete-overlay (car all))
 887       (mapcar 'delete-overlay (cdr all)))
 888     (setq recentf-edit-selected-items nil)
 889     ;; Insert the dialog header
 890     (widget-insert "Select the files to be deleted from the 'recentf-list'.\n\n")
 891     (widget-insert "Click on Ok to update the list. ")
 892     (widget-insert "Click on Cancel or type \"q\" to quit.\n")
 893     ;; Insert the list of files as checkboxes
 894     (mapcar (function
 895              (lambda (item)
 896                (widget-create 'checkbox
 897                               :value nil ; unselected checkbox
 898                               :format "\n %[%v%]  %t"
 899                               :tag item
 900                               :notify 'recentf-edit-list-action)))
 901             recentf-list)
 902     (widget-insert "\n\n")
 903     ;; Insert the Ok button
 904     (widget-create 'push-button
 905                    :notify (lambda (&rest ignore)
 906                              (if recentf-edit-selected-items
 907                                  (progn (kill-buffer (current-buffer))
 908                                         (mapcar (function
 909                                                  (lambda (item)
 910                                                    (setq recentf-list
 911                                                          (delq item recentf-list))))
 912                                                 recentf-edit-selected-items)
 913                                         (message "%S file(s) removed from the list"
 914                                                  (length recentf-edit-selected-items))
 915                                         (setq recentf-update-menu-p t))
 916                                (message "No file selected.")))
 917                    "Ok")
 918     (widget-insert " ")
 919     ;; Insert the Cancel button
 920     (widget-create 'push-button
 921                    :notify 'recentf-cancel-dialog
 922                    "Cancel")
 923     (recentf-dialog-mode)
 924     (widget-setup)
 925     (goto-char (point-min))))
 926
 927 ;;;###autoload
 928 (defun recentf-cleanup ()
 929   "Remove all non-readable and excluded files from `recentf-list'."
 930   (interactive)
 931   (let ((count (length recentf-list)))
 932     (setq recentf-list
 933           (delq nil
 934                 (mapcar (function
 935                          (lambda (filename)
 936                            (and (file-readable-p filename)
 937                                 (recentf-include-p filename)
 938                                 filename)))
 939                         recentf-list)))
 940     (setq count (- count (length recentf-list)))
 941     (message "%s removed from the list"
 942              (cond ((= count 0) "No file")
 943                    ((= count 1) "One file")
 944                    (t (format "%d files" count)))))
 945   (setq recentf-update-menu-p t))
 946
 947 (defun recentf-open-files-action (widget &rest ignore)
 948   "Button widget action used by `recentf-open-files' to open a file."
 949   (kill-buffer (current-buffer))
 950   (funcall recentf-menu-action (widget-value widget)))
 951
 952 (defvar recentf-open-files-item-shift ""
 953   "String used by `recentf-open-files' to shift right sub-menu
 954 items.")
 955
 956 (defun recentf-open-files-item (menu-element)
 957   "Function called by `recentf-open-files' to insert a menu-element
 958 item in the current interaction buffer."
 959   (let ((menu-item (car menu-element))
 960         (file-path (cdr menu-element)))
 961     (if (consp file-path)               ; This is a sub-menu
 962         (let* ((shift recentf-open-files-item-shift)
 963                (recentf-open-files-item-shift (concat shift "  ")))
 964           (widget-create 'item
 965                          :tag menu-item
 966                          :sample-face 'bold
 967                          :format (concat shift "%{%t%}:\n"))
 968           (mapcar 'recentf-open-files-item
 969                   file-path)
 970           (widget-insert "\n"))
 971       (widget-create 'push-button
 972                      :button-face 'default
 973                      :tag menu-item
 974                      :help-echo (concat "Open " file-path)
 975                      :format (concat recentf-open-files-item-shift "%[%t%]")
 976                      :notify 'recentf-open-files-action
 977                      file-path)
 978       (widget-insert "\n"))))
 979
 980 ;;;###autoload
 981 (defun recentf-open-files (&optional files buffer-name)
 982   "Open a buffer that allows the user to choose a file to open from
 983 the list of recently opened files. The optional argument FILES may be
 984 used to specify the list, otherwise recentf-list is used. The optional
 985 argument BUFFER-NAME specifies which buffer to use for the interaction."
 986   (interactive)
 987   (if (null files)
 988       (setq files recentf-list))
 989   (if (null buffer-name)
 990       (setq buffer-name (concat "*" recentf-menu-title "*")))
 991   (with-current-buffer (get-buffer-create buffer-name)
 992     (switch-to-buffer (current-buffer))
 993     (kill-all-local-variables)
 994     (let ((inhibit-read-only t))
 995       (erase-buffer))
 996     (let ((all (overlay-lists)))
 997       ;; Delete all the overlays.
 998       (mapcar 'delete-overlay (car all))
 999       (mapcar 'delete-overlay (cdr all)))
1000     ;; Insert the dialog header
1001     (widget-insert "Click on a file to open it. ")
1002     (widget-insert "Click on Cancel or type \"q\" to quit.\n\n" )
1003     ;; Insert the list of files as buttons
1004     (let ((recentf-open-files-item-shift ""))
1005       (mapcar 'recentf-open-files-item
1006               (recentf-apply-menu-filter
1007                recentf-menu-filter
1008                (mapcar 'recentf-make-default-menu-element files))))
1009     (widget-insert "\n")
1010     ;; Insert the Cancel button
1011     (widget-create 'push-button
1012                    :notify 'recentf-cancel-dialog
1013                    "Cancel")
1014     (recentf-dialog-mode)
1015     (widget-setup)
1016     (goto-char (point-min))))
1017
1018 ;;;###autoload
1019 (defun recentf-open-more-files ()
1020   "Allow the user to open files that are not in the menu."
1021   (interactive)
1022   (recentf-open-files (nthcdr recentf-max-menu-items recentf-list)
1023                       (concat "*" recentf-menu-title " - More*")))
1024
1025 ;;;###autoload
1026 (defun recentf-mode (&optional arg)
1027   "Toggle recentf mode.
1028 With prefix ARG, turn recentf mode on if and only if ARG is positive.
1029 Returns the new status of recentf mode (non-nil means on).
1030
1031 When recentf mode is enabled, it maintains a menu for visiting files that
1032 were operated on recently."
1033   (interactive "P")
1034   (let ((on-p (if arg
1035                   (> (prefix-numeric-value arg) 0)
1036                 (not recentf-mode))))
1037     (if on-p
1038         (unless recentf-initialized-p
1039           (setq recentf-initialized-p t)
1040           (if (file-readable-p recentf-save-file)
1041               (load-file recentf-save-file))
1042           (setq recentf-update-menu-p t)
1043           (add-hook 'find-file-hooks       'recentf-add-file-hook)
1044           (add-hook 'write-file-hooks      'recentf-add-file-hook)
1045           (add-hook 'menu-bar-update-hook  'recentf-update-menu-hook)
1046           (add-hook 'kill-emacs-hook       'recentf-save-list))
1047       (when recentf-initialized-p
1048         (setq recentf-initialized-p nil)
1049         (recentf-save-list)
1050         (easy-menu-remove-item nil recentf-menu-path recentf-menu-title)
1051         (remove-hook 'find-file-hooks       'recentf-add-file-hook)
1052         (remove-hook 'write-file-hooks      'recentf-add-file-hook)
1053         (remove-hook 'menu-bar-update-hook  'recentf-update-menu-hook)
1054         (remove-hook 'kill-emacs-hook       'recentf-save-list)))
1055     (setq recentf-mode on-p)))
1056
1057 (provide 'recentf)
1058
1059 (run-hooks 'recentf-load-hook)
1060
1061 ;;; recentf.el ends here.