lisp/recentf.el

   1 ;;; recentf.el --- setup a menu of recently opened files
   2
   3 ;; Copyright (C) 1999, 2000, 2001, 2002, 2003
   4 ;;   Free Software Foundation, Inc.
   5
   6 ;; Author: David Ponce <david@dponce.com>
   7 ;; Created: July 19 1999
   8 ;; Maintainer: FSF
   9 ;; Keywords: files
  10
  11 (defconst recentf-version "$Revision: 1.23 $")
  12
  13 ;; This file is part of GNU Emacs.
  14
  15 ;; GNU Emacs is free software; you can redistribute it and/or modify
  16 ;; it under the terms of the GNU General Public License as published
  17 ;; by the Free Software Foundation; either version 2, or (at your
  18 ;; option) any later version.
  19
  20 ;; GNU Emacs is distributed in the hope that it will be useful,
  21 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  22 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  23 ;; GNU General Public License for more details.
  24
  25 ;; You should have received a copy of the GNU General Public License
  26 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  27 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  28 ;; Boston, MA 02111-1307, USA.
  29
  30 ;;; Commentary:
  31
  32 ;; This package maintains a menu for visiting files that were operated
  33 ;; on recently.  When enabled a new "Open Recent" submenu is displayed
  34 ;; in the "Files" menu.  The recent files list is automatically saved
  35 ;; across Emacs sessions.  You can customize the number of recent
  36 ;; files displayed, the location of the menu and others options (see
  37 ;; the source code for details).
  38
  39 ;;; History:
  40 ;;
  41
  42 ;;; Code:
  43 (require 'easymenu)
  44 (require 'wid-edit)
  45 (require 'timer)
  46
  47 ;;; Internal data
  48 ;;
  49 (defvar recentf-list nil
  50   "List of recently opened files.")
  51
  52 (defvar recentf-data-cache nil
  53   "Cache of data used to build the recentf menu.
  54 The menu is rebuilt when this data has changed.")
  55 \f
  56 ;;; Customization
  57 ;;
  58 (defgroup recentf nil
  59   "Maintain a menu of recently opened files."
  60   :version "21.1"
  61   :group 'files)
  62
  63 (defgroup recentf-filters nil
  64   "Group to customize recentf menu filters.
  65 You should define the options of your own filters in this group."
  66   :group 'recentf)
  67
  68 (defcustom recentf-max-saved-items 20
  69   "*Maximum number of items of the recent list that will be saved.
  70 nil means to save the whole list.
  71 See the command `recentf-save-list'."
  72   :group 'recentf
  73   :type 'integer)
  74
  75 (defcustom recentf-save-file "~/.recentf"
  76   "*File to save the recent list into."
  77   :group 'recentf
  78   :type 'file)
  79
  80 (defcustom recentf-exclude nil
  81   "*List of regexps for filenames excluded from the recent list."
  82   :group 'recentf
  83   :type '(repeat regexp))
  84
  85 (defun recentf-menu-customization-changed (variable value)
  86   "Function called when the recentf menu customization has changed.
  87 Set VARIABLE with VALUE, and force a rebuild of the recentf menu."
  88   (when (featurep 'recentf)
  89     ;; Unavailable until recentf has been loaded.
  90     (recentf-clear-data))
  91   (set-default variable value))
  92
  93 (defcustom recentf-menu-title "Open Recent"
  94   "*Name of the recentf menu."
  95   :group 'recentf
  96   :type 'string
  97   :set 'recentf-menu-customization-changed)
  98
  99 (defcustom recentf-menu-path '("files")
 100   "*Path where to add the recentf menu.
 101 If nil add it at top level (see also `easy-menu-change')."
 102   :group 'recentf
 103   :type '(choice (const :tag "Top Level" nil)
 104                  (sexp :tag "Menu Path"))
 105   :set 'recentf-menu-customization-changed)
 106
 107 (defcustom recentf-menu-before "Open File..."
 108   "*Name of the menu before which the recentf menu will be added.
 109 If nil add it at end of menu (see also `easy-menu-change')."
 110   :group 'recentf
 111   :type '(choice (string :tag "Name")
 112                  (const :tag "Last" nil))
 113   :set 'recentf-menu-customization-changed)
 114
 115 (defcustom recentf-menu-action 'recentf-find-file
 116   "*Function to invoke with a filename item of the recentf menu.
 117 The default is to call `recentf-find-file' to edit the selected file."
 118   :group 'recentf
 119   :type 'function
 120   :set 'recentf-menu-customization-changed)
 121
 122 (defcustom recentf-max-menu-items 10
 123   "*Maximum number of items in the recentf menu."
 124   :group 'recentf
 125   :type 'integer
 126   :set 'recentf-menu-customization-changed)
 127
 128 (defcustom recentf-menu-filter nil
 129   "*Function used to filter files displayed in the recentf menu.
 130 nil means no filter.  The following functions are predefined:
 131
 132 - `recentf-sort-ascending'
 133     Sort menu items in ascending order.
 134 - `recentf-sort-descending'
 135     Sort menu items in descending order.
 136 - `recentf-sort-basenames-ascending'
 137     Sort menu items by filenames sans directory in ascending order.
 138 - `recentf-sort-basenames-descending'
 139     Sort menu items by filenames sans directory in descending order.
 140 - `recentf-sort-directories-ascending'
 141     Sort menu items by directories in ascending order.
 142 - `recentf-sort-directories-descending'
 143     Sort menu items by directories in descending order.
 144 - `recentf-show-basenames'
 145     Show filenames sans directory in menu items.
 146 - `recentf-show-basenames-ascending'
 147     Show filenames sans directory in ascending order.
 148 - `recentf-show-basenames-descending'
 149     Show filenames sans directory in descending order.
 150 - `recentf-relative-filter'
 151     Show filenames relative to `default-directory'.
 152 - `recentf-arrange-by-rule'
 153     Show sub-menus following user defined rules.
 154 - `recentf-arrange-by-mode'
 155     Show a sub-menu for each major mode.
 156 - `recentf-arrange-by-dir'
 157     Show a sub-menu for each directory.
 158 - `recentf-filter-changer'
 159     Manage a ring of filters.
 160
 161 The filter function is called with one argument, the list of menu
 162 elements used to build the menu and must return a new list of menu
 163 elements (see `recentf-make-menu-element' for menu element form)."
 164   :group 'recentf
 165   :type '(radio (const nil)
 166                 (function-item recentf-sort-ascending)
 167                 (function-item recentf-sort-descending)
 168                 (function-item recentf-sort-basenames-ascending)
 169                 (function-item recentf-sort-basenames-descending)
 170                 (function-item recentf-sort-directories-ascending)
 171                 (function-item recentf-sort-directories-descending)
 172                 (function-item recentf-show-basenames)
 173                 (function-item recentf-show-basenames-ascending)
 174                 (function-item recentf-show-basenames-descending)
 175                 (function-item recentf-relative-filter)
 176                 (function-item recentf-arrange-by-rule)
 177                 (function-item recentf-arrange-by-mode)
 178                 (function-item recentf-arrange-by-dir)
 179                 (function-item recentf-filter-changer)
 180                 function)
 181   :set 'recentf-menu-customization-changed)
 182
 183 (defcustom recentf-menu-append-commands-flag t
 184   "*non-nil means to append command items to the menu."
 185   :group 'recentf
 186   :type 'boolean
 187   :set 'recentf-menu-customization-changed)
 188
 189 (defvaralias 'recentf-menu-append-commands-p
 190   'recentf-menu-append-commands-flag)
 191 (make-obsolete-variable 'recentf-menu-append-commands-p
 192                         'recentf-menu-append-commands-flag
 193                         "21.4")
 194
 195 (defcustom recentf-keep-non-readable-files-flag nil
 196   "*non-nil means to keep non readable files in the recent list."
 197   :group 'recentf
 198   :type 'boolean)
 199
 200 (defvaralias 'recentf-keep-non-readable-files-p
 201   'recentf-keep-non-readable-files-flag)
 202 (make-obsolete-variable 'recentf-keep-non-readable-files-p
 203                         'recentf-keep-non-readable-files-flag
 204                         "21.4")
 205
 206 (defcustom recentf-auto-cleanup 'mode
 207   "*Define when to automatically cleanup the recent list.
 208 The following values can be set:
 209
 210 - `mode'
 211     Cleanup when turning the mode on (default).
 212 - `never'
 213     Never cleanup the list automatically.
 214 - A number
 215     Cleanup each time Emacs has been idle that number of seconds.
 216 - A time string
 217     Cleanup at specified time string, for example at \"11:00pm\".
 218
 219 Setting this variable directly does not take effect;
 220 use \\[customize].
 221
 222 See also the command `recentf-cleanup', that can be used to manually
 223 cleanup the list."
 224   :group 'recentf
 225   :type '(radio (const  :tag "When mode enabled"
 226                         :value mode)
 227                 (const  :tag "Never"
 228                         :value never)
 229                 (number :tag "When idle that seconds"
 230                         :value 300)
 231                 (string :tag "At time"
 232                         :value "11:00pm"))
 233   :set (lambda (variable value)
 234          (set-default variable value)
 235          (when (featurep 'recentf)
 236            ;; Unavailable until recentf has been loaded.
 237            (recentf-auto-cleanup))))
 238
 239 (defcustom recentf-load-hook nil
 240    "*Normal hook run at end of loading the `recentf' package."
 241   :group 'recentf
 242   :type 'hook)
 243
 244 (defcustom recentf-filename-handler nil
 245   "Function to call to process filename handled by recentf.
 246 It is passed a filename to give a chance to transform it.
 247 If it returns nil, the filename is left unchanged."
 248   :group 'recentf
 249   :type 'function)
 250 \f
 251 ;;; Utilities
 252 ;;
 253 (defconst recentf-case-fold-search
 254   (memq system-type '(vax-vms windows-nt cygwin))
 255   "Non-nil if recentf searches and matches should ignore case.")
 256
 257 (defsubst recentf-string-equal (s1 s2)
 258   "Return non-nil if strings S1 and S2 have identical contents.
 259 Ignore case if `recentf-case-fold-search' is non-nil."
 260   (if recentf-case-fold-search
 261       (string-equal (downcase s1) (downcase s2))
 262     (string-equal s1 s2)))
 263
 264 (defsubst recentf-string-lessp (s1 s2)
 265   "Return non-nil if string S1 is less than S2 in lexicographic order.
 266 Ignore case if `recentf-case-fold-search' is non-nil."
 267   (if recentf-case-fold-search
 268       (string-lessp (downcase s1) (downcase s2))
 269     (string-lessp s1 s2)))
 270
 271 (defun recentf-string-member (elt list)
 272   "Return non-nil if ELT is an element of LIST.
 273 The value is actually the tail of LIST whose car is ELT.
 274 ELT must be a string and LIST a list of strings.
 275 Ignore case if `recentf-case-fold-search' is non-nil."
 276   (while (and list (not (recentf-string-equal elt (car list))))
 277     (setq list (cdr list)))
 278   list)
 279
 280 (defsubst recentf-trunc-list (l n)
 281   "Return from L the list of its first N elements."
 282   (let (nl)
 283     (while (and l (> n 0))
 284       (setq nl (cons (car l) nl)
 285             n  (1- n)
 286             l  (cdr l)))
 287     (nreverse nl)))
 288
 289 (defun recentf-dump-variable (variable &optional limit)
 290   "Insert a \"(setq VARIABLE value)\" in the current buffer.
 291 When the value of VARIABLE is a list, optional argument LIMIT
 292 specifies a maximum number of elements to insert.  By default insert
 293 the full list."
 294   (let ((value (symbol-value variable)))
 295     (if (atom value)
 296         (insert (format "\n(setq %S %S)\n" variable value))
 297       (when (and (integerp limit) (> limit 0))
 298         (setq value (recentf-trunc-list value limit)))
 299       (insert (format "\n(setq %S\n      '(" variable))
 300       (dolist (e value)
 301         (insert (format "\n        %S" e)))
 302       (insert "\n        ))\n"))))
 303
 304 (defvar recentf-auto-cleanup-timer nil
 305   "Timer used to automatically cleanup the recent list.
 306 See also the option `recentf-auto-cleanup'.")
 307
 308 (defun recentf-auto-cleanup ()
 309   "Automatic cleanup of the recent list."
 310   (when (timerp recentf-auto-cleanup-timer)
 311     (cancel-timer recentf-auto-cleanup-timer))
 312   (when recentf-mode
 313     (setq recentf-auto-cleanup-timer
 314           (cond
 315            ((eq 'mode recentf-auto-cleanup)
 316             (recentf-cleanup)
 317             nil)
 318            ((numberp recentf-auto-cleanup)
 319             (run-with-idle-timer
 320              recentf-auto-cleanup t 'recentf-cleanup))
 321            ((stringp recentf-auto-cleanup)
 322             (run-at-time
 323              recentf-auto-cleanup nil 'recentf-cleanup))))))
 324 \f
 325 ;;; File functions
 326 ;;
 327 (defsubst recentf-push (filename)
 328   "Push FILENAME into the recent list, if it isn't there yet.
 329 If it is there yet, move it at the beginning of the list.
 330 If `recentf-case-fold-search' is non-nil, ignore case when comparing
 331 filenames."
 332   (let ((m (recentf-string-member filename recentf-list)))
 333     (and m (setq recentf-list (delq (car m) recentf-list)))
 334     (push filename recentf-list)))
 335
 336 (defsubst recentf-expand-file-name (name)
 337   "Convert filename NAME to absolute, and canonicalize it.
 338 See also the function `expand-file-name'.
 339 If defined, call the function `recentf-filename-handler' to post
 340 process the canonical name."
 341   (let* ((filename (expand-file-name name)))
 342     (or (and recentf-filename-handler
 343              (funcall recentf-filename-handler filename))
 344         filename)))
 345
 346 (defun recentf-include-p (filename)
 347   "Return t if FILENAME match none of the `recentf-exclude' regexps."
 348   (let ((case-fold-search recentf-case-fold-search)
 349         (rl recentf-exclude))
 350     (while (and rl (not (string-match (car rl) filename)))
 351       (setq rl (cdr rl)))
 352     (null rl)))
 353
 354 (defsubst recentf-add-file (filename)
 355   "Add or move FILENAME at the beginning of the recent list.
 356 Does nothing it if it matches any of the `recentf-exclude' regexps."
 357   (setq filename (recentf-expand-file-name filename))
 358   (when (recentf-include-p filename)
 359     (recentf-push filename)))
 360
 361 (defsubst recentf-remove-if-non-readable (filename)
 362   "Remove FILENAME from the recent list, if file is not readable.
 363 Return non-nil if FILENAME has been removed."
 364   (unless (file-readable-p filename)
 365     (let ((m (recentf-string-member
 366               (recentf-expand-file-name filename) recentf-list)))
 367       (and m (setq recentf-list (delq (car m) recentf-list))))))
 368
 369 (defun recentf-find-file (filename)
 370   "Edit file FILENAME using `find-file'.
 371 If the file does not exist or is non readable, and
 372 `recentf-keep-non-readable-files-flag' is nil, it is not edited and
 373 its name is removed from the recent list."
 374   (if (and (not recentf-keep-non-readable-files-flag)
 375            (recentf-remove-if-non-readable filename))
 376       (message "File `%s' not found" filename)
 377     (find-file filename)))
 378
 379 (defsubst recentf-directory-compare (f1 f2)
 380   "Compare absolute filenames F1 and F2.
 381 First compare directories, then filenames sans directory.
 382 Return non-nil if F1 is less than F2."
 383   (let ((d1 (file-name-directory f1))
 384         (d2 (file-name-directory f2)))
 385     (if (recentf-string-equal d1 d2)
 386         (recentf-string-lessp (file-name-nondirectory f1)
 387                               (file-name-nondirectory f2))
 388       (recentf-string-lessp d1 d2))))
 389 \f
 390 ;;; Menu building
 391 ;;
 392 (defvar recentf-menu-items-for-commands
 393   (list ["Cleanup list"
 394          recentf-cleanup
 395          :help "Remove all non-readable and excluded files from the recent list"
 396          :active t]
 397         ["Edit list..."
 398          recentf-edit-list
 399          :help "Edit the files that are kept in the recent list"
 400          :active t]
 401         ["Save list now"
 402          recentf-save-list
 403          :help "Save the list of recently opened files now"
 404          :active t]
 405         ["Options..."
 406          (customize-group "recentf")
 407          :help "Customize recently opened files menu and options"
 408          :active t]
 409         )
 410   "List of menu items for recentf commands.")
 411
 412 (defvar recentf-menu-filter-commands nil
 413   "This variable can be used by menu filters to setup their own command menu.
 414 If non-nil it must contain a list of valid menu-items to be appended
 415 to the recent file list part of the menu.  Before calling a menu
 416 filter function this variable is reset to nil.")
 417
 418 (defsubst recentf-elements (n)
 419   "Return a list of the first N elements of the recent list."
 420   (recentf-trunc-list recentf-list n))
 421
 422 (defsubst recentf-make-menu-element (menu-item menu-value)
 423   "Create a new menu-element.
 424 A menu element is a pair (MENU-ITEM . MENU-VALUE), where MENU-ITEM is
 425 the menu item string displayed.  MENU-VALUE is the file to be open
 426 when the corresponding MENU-ITEM is selected.  Or it is a
 427 pair (SUB-MENU-TITLE . MENU-ELEMENTS) where SUB-MENU-TITLE is a
 428 sub-menu title and MENU-ELEMENTS is the list of menu elements in the
 429 sub-menu."
 430   (cons menu-item menu-value))
 431
 432 (defsubst recentf-menu-element-item (e)
 433   "Return the item part of the menu-element E."
 434   (car e))
 435
 436 (defsubst recentf-menu-element-value (e)
 437   "Return the value part of the menu-element E."
 438   (cdr e))
 439
 440 (defsubst recentf-set-menu-element-item (e item)
 441   "Change the item part of menu-element E to ITEM."
 442   (setcar e item))
 443
 444 (defsubst recentf-set-menu-element-value (e value)
 445   "Change the value part of menu-element E to VALUE."
 446   (setcdr e value))
 447
 448 (defsubst recentf-sub-menu-element-p (e)
 449   "Return non-nil if menu-element E defines a sub-menu."
 450   (consp (recentf-menu-element-value e)))
 451
 452 (defsubst recentf-make-default-menu-element (file)
 453   "Make a new default menu element with FILE.
 454 This a menu element (FILE . FILE)."
 455   (recentf-make-menu-element file file))
 456
 457 (defsubst recentf-menu-elements (n)
 458   "Return a list of the first N default menu elements from the recent list.
 459 See also `recentf-make-default-menu-element'."
 460   (mapcar 'recentf-make-default-menu-element
 461           (recentf-elements n)))
 462
 463 (defun recentf-apply-menu-filter (filter l)
 464   "Apply function FILTER to the list of menu-elements L.
 465 It takes care of sub-menu elements in L and recursively apply FILTER
 466 to them.  It is guaranteed that FILTER receives only a list of single
 467 menu-elements (no sub-menu)."
 468   (if (and l (functionp filter))
 469       (let ((case-fold-search recentf-case-fold-search)
 470             elts others)
 471         ;; split L into two sub-listes, one of sub-menus elements and
 472         ;; another of single menu elements.
 473         (dolist (elt l)
 474           (if (recentf-sub-menu-element-p elt)
 475               (push elt elts)
 476             (push elt others)))
 477         ;; Apply FILTER to single elements.
 478         (when others
 479           (setq others (funcall filter (nreverse others))))
 480         ;; Apply FILTER to sub-menu elements.
 481         (setq l nil)
 482         (dolist (elt elts)
 483           (recentf-set-menu-element-value
 484            elt (recentf-apply-menu-filter
 485                 filter (recentf-menu-element-value elt)))
 486           (push elt l))
 487         ;; Return the new filtered menu element list.
 488         (nconc l others))
 489     l))
 490
 491 (defun recentf-make-menu-items ()
 492   "Make menu items from the recent list."
 493   (setq recentf-menu-filter-commands nil)
 494   (let ((file-items
 495          (mapcar 'recentf-make-menu-item
 496                  (recentf-apply-menu-filter
 497                   recentf-menu-filter
 498                   (recentf-menu-elements recentf-max-menu-items)))))
 499     (append (or file-items (list ["No files" t
 500                                   :help "No recent file to open"
 501                                   :active nil]))
 502             (and (< recentf-max-menu-items (length recentf-list))
 503                  (list ["More..." recentf-open-more-files
 504                         :help "Open files that are not in the menu"
 505                         :active t]))
 506             (and recentf-menu-filter-commands
 507                  (cons "---"
 508                        recentf-menu-filter-commands))
 509             (and recentf-menu-append-commands-flag
 510                  (cons "---"
 511                        recentf-menu-items-for-commands)))))
 512
 513 (defsubst recentf-make-menu-item (elt)
 514   "Make a menu item from menu element ELT."
 515   (let ((item  (recentf-menu-element-item  elt))
 516         (value (recentf-menu-element-value elt)))
 517     (if (recentf-sub-menu-element-p elt)
 518         (cons item (mapcar 'recentf-make-menu-item value))
 519       (vector item (list recentf-menu-action value)
 520               :help (concat "Open " value)
 521               :active t))))
 522
 523 (defun recentf-clear-data ()
 524   "Clear data used to build the recentf menu.
 525 This force a rebuild of the menu."
 526   (easy-menu-remove-item nil recentf-menu-path recentf-menu-title)
 527   (setq recentf-data-cache nil))
 528 \f
 529 ;;; Predefined menu filters
 530 ;;
 531 (defsubst recentf-sort-ascending (l)
 532   "Sort the list of menu elements L in ascending order.
 533 The MENU-ITEM part of each menu element is compared."
 534   (sort (copy-sequence l)
 535         #'(lambda (e1 e2)
 536             (recentf-string-lessp
 537              (recentf-menu-element-item e1)
 538              (recentf-menu-element-item e2)))))
 539
 540 (defsubst recentf-sort-descending (l)
 541   "Sort the list of menu elements L in descending order.
 542 The MENU-ITEM part of each menu element is compared."
 543   (sort (copy-sequence l)
 544         #'(lambda (e1 e2)
 545             (recentf-string-lessp
 546              (recentf-menu-element-item e2)
 547              (recentf-menu-element-item e1)))))
 548
 549 (defsubst recentf-sort-basenames-ascending (l)
 550   "Sort the list of menu elements L in ascending order.
 551 Only filenames sans directory are compared."
 552   (sort (copy-sequence l)
 553         #'(lambda (e1 e2)
 554             (recentf-string-lessp
 555              (file-name-nondirectory (recentf-menu-element-value e1))
 556              (file-name-nondirectory (recentf-menu-element-value e2))))))
 557
 558 (defsubst recentf-sort-basenames-descending (l)
 559   "Sort the list of menu elements L in descending order.
 560 Only filenames sans directory are compared."
 561   (sort (copy-sequence l)
 562         #'(lambda (e1 e2)
 563             (recentf-string-lessp
 564              (file-name-nondirectory (recentf-menu-element-value e2))
 565              (file-name-nondirectory (recentf-menu-element-value e1))))))
 566
 567 (defsubst recentf-sort-directories-ascending (l)
 568   "Sort the list of menu elements L in ascending order.
 569 Compares directories then filenames to order the list."
 570   (sort (copy-sequence l)
 571         #'(lambda (e1 e2)
 572             (recentf-directory-compare
 573              (recentf-menu-element-value e1)
 574              (recentf-menu-element-value e2)))))
 575
 576 (defsubst recentf-sort-directories-descending (l)
 577   "Sort the list of menu elements L in descending order.
 578 Compares directories then filenames to order the list."
 579   (sort (copy-sequence l)
 580         #'(lambda (e1 e2)
 581             (recentf-directory-compare
 582              (recentf-menu-element-value e2)
 583              (recentf-menu-element-value e1)))))
 584
 585 (defun recentf-show-basenames (l &optional no-dir)
 586   "Filter the list of menu elements L to show filenames sans directory.
 587 When a filename is duplicated, it is appended a sequence number if
 588 optional argument NO-DIR is non-nil, or its directory otherwise."
 589   (let (filtered-names filtered-list full name counters sufx)
 590     (dolist (elt l (nreverse filtered-list))
 591       (setq full (recentf-menu-element-value elt)
 592             name (file-name-nondirectory full))
 593       (if (not (member name filtered-names))
 594           (push name filtered-names)
 595         (if no-dir
 596             (if (setq sufx (assoc name counters))
 597                 (setcdr sufx (1+ (cdr sufx)))
 598               (setq sufx 1)
 599               (push (cons name sufx) counters))
 600           (setq sufx (file-name-directory full)))
 601         (setq name (format "%s(%s)" name sufx)))
 602       (push (recentf-make-menu-element name full) filtered-list))))
 603
 604 (defsubst recentf-show-basenames-ascending (l)
 605   "Filter the list of menu elements L to show filenames sans directory.
 606 Filenames are sorted in ascending order.
 607 This filter combines the `recentf-sort-basenames-ascending' and
 608 `recentf-show-basenames' filters."
 609   (recentf-show-basenames (recentf-sort-basenames-ascending l)))
 610
 611 (defsubst recentf-show-basenames-descending (l)
 612   "Filter the list of menu elements L to show filenames sans directory.
 613 Filenames are sorted in descending order.
 614 This filter combines the `recentf-sort-basenames-descending' and
 615 `recentf-show-basenames' filters."
 616   (recentf-show-basenames (recentf-sort-basenames-descending l)))
 617
 618 (defun recentf-relative-filter (l)
 619   "Filter the list of menu-elements L to show relative filenames.
 620 Filenames are relative to the `default-directory'."
 621   (mapcar #'(lambda (menu-element)
 622               (let* ((ful (recentf-menu-element-value menu-element))
 623                      (rel (file-relative-name ful default-directory)))
 624                 (if (string-match "^\\.\\." rel)
 625                     menu-element
 626                   (recentf-make-menu-element rel ful))))
 627           l))
 628 \f
 629 ;;; Rule based menu filters
 630 ;;
 631 (defcustom recentf-arrange-rules
 632   '(
 633     ("Elisp files (%d)" ".\\.el$")
 634     ("Java files (%d)"  ".\\.java$")
 635     ("C/C++ files (%d)" "c\\(pp\\)?$")
 636     )
 637   "*List of rules used by `recentf-arrange-by-rule' to build sub-menus.
 638 A rule is a pair (SUB-MENU-TITLE . MATCHER).  SUB-MENU-TITLE is the
 639 displayed title of the sub-menu where a '%d' `format' pattern is
 640 replaced by the number of items in the sub-menu.  MATCHER is a regexp
 641 or a list of regexps.  Items matching one of the regular expressions in
 642 MATCHER are added to the corresponding sub-menu."
 643   :group 'recentf-filters
 644   :type '(repeat (cons string (repeat regexp)))
 645   :set 'recentf-menu-customization-changed)
 646
 647 (defcustom recentf-arrange-by-rule-others "Other files (%d)"
 648   "*Title of the `recentf-arrange-by-rule' sub-menu.
 649 This is for the menu where items that don't match any
 650 `recentf-arrange-rules' are displayed.  If nil these items are
 651 displayed in the main recent files menu.  A '%d' `format' pattern in
 652 the title is replaced by the number of items in the sub-menu."
 653   :group 'recentf-filters
 654   :type '(choice (const  :tag "Main menu" nil)
 655                  (string :tag "Title"))
 656   :set 'recentf-menu-customization-changed)
 657
 658 (defcustom recentf-arrange-by-rules-min-items 0
 659   "*Minimum number of items in a `recentf-arrange-by-rule' sub-menu.
 660 If the number of items in a sub-menu is less than this value the
 661 corresponding sub-menu items are displayed in the main recent files
 662 menu or in the `recentf-arrange-by-rule-others' sub-menu if
 663 defined."
 664   :group 'recentf-filters
 665   :type 'number
 666   :set 'recentf-menu-customization-changed)
 667
 668 (defcustom recentf-arrange-by-rule-subfilter nil
 669   "*Function called by a rule based filter to filter sub-menu elements.
 670 nil means no filter.  See also `recentf-menu-filter'.
 671 You can't use another rule based filter here."
 672   :group 'recentf-filters
 673   :type '(choice (const nil) function)
 674   :set (lambda (variable value)
 675          (when (memq value '(recentf-arrange-by-rule
 676                              recentf-arrange-by-mode
 677                              recentf-arrange-by-dir))
 678            (error "Recursive use of a rule based filter"))
 679          (recentf-menu-customization-changed variable value)))
 680
 681 (defun recentf-match-rule-p (matcher filename)
 682   "Return non-nil if the rule specified by MATCHER match FILENAME.
 683 See `recentf-arrange-rules' for details on MATCHER."
 684   (if (stringp matcher)
 685       (string-match matcher filename)
 686     (while (and (consp matcher)
 687                 (not (string-match (car matcher) filename)))
 688       (setq matcher (cdr matcher)))
 689     matcher))
 690
 691 (defun recentf-arrange-by-rule (l)
 692   "Filter the list of menu-elements L.
 693 Arrange them in sub-menus following rules in `recentf-arrange-rules'."
 694   (if (not recentf-arrange-rules)
 695       l
 696     (let ((menus (mapcar #'(lambda (r) (list (car r)))
 697                          recentf-arrange-rules))
 698           menu others min file rules elts count)
 699       (dolist (elt l)
 700         (setq file  (recentf-menu-element-value elt)
 701               rules recentf-arrange-rules
 702               elts  menus
 703               menu  nil)
 704         (while (and (not menu) rules)
 705           (when (recentf-match-rule-p (cdar rules) file)
 706             (setq menu (car elts))
 707             (recentf-set-menu-element-value
 708              menu (cons elt (recentf-menu-element-value menu))))
 709           (setq rules (cdr rules)
 710                 elts  (cdr elts)))
 711         (unless menu
 712           (push elt others)))
 713
 714       (setq l nil
 715             min (if (natnump recentf-arrange-by-rules-min-items)
 716                     recentf-arrange-by-rules-min-items 0))
 717       (dolist (menu menus)
 718         (when (setq elts (recentf-menu-element-value menu))
 719           (setq count (length elts))
 720           (if (< count min)
 721               (setq others (nconc elts others))
 722             (recentf-set-menu-element-item
 723              menu (format (recentf-menu-element-item menu) count))
 724             (recentf-set-menu-element-value
 725              menu (recentf-apply-menu-filter
 726                    recentf-arrange-by-rule-subfilter (nreverse elts)))
 727             (push menu l))))
 728
 729       (if (and (stringp recentf-arrange-by-rule-others) others)
 730           (nreverse
 731            (cons
 732             (recentf-make-menu-element
 733              (format recentf-arrange-by-rule-others (length others))
 734              (recentf-apply-menu-filter
 735               recentf-arrange-by-rule-subfilter (nreverse others)))
 736             l))
 737         (nconc
 738          (nreverse l)
 739          (recentf-apply-menu-filter
 740           recentf-arrange-by-rule-subfilter (nreverse others)))))
 741     ))
 742 \f
 743 ;;; Predefined rule based menu filters
 744 ;;
 745 (defun recentf-build-mode-rules ()
 746   "Convert `auto-mode-alist' to menu filter rules.
 747 Rules obey `recentf-arrange-rules' format."
 748   (let ((case-fold-search recentf-case-fold-search)
 749         regexp rule-name rule rules)
 750     (dolist (mode auto-mode-alist)
 751       (setq regexp (car mode)
 752             mode   (cdr mode))
 753       (when (symbolp mode)
 754         (setq rule-name (symbol-name mode))
 755         (if (string-match "\\(.*\\)-mode$" rule-name)
 756             (setq rule-name (match-string 1 rule-name)))
 757         (setq rule-name (concat rule-name " (%d)")
 758               rule (assoc rule-name rules))
 759         (if rule
 760             (setcdr rule (cons regexp (cdr rule)))
 761           (push (list rule-name regexp) rules))))
 762     ;; It is important to preserve auto-mode-alist order
 763     ;; to ensure the right file <-> mode association
 764     (nreverse rules)))
 765
 766 (defun recentf-arrange-by-mode (l)
 767   "Split the list of menu-elements L into sub-menus by major mode."
 768   (let ((recentf-arrange-rules (recentf-build-mode-rules))
 769         (recentf-arrange-by-rule-others "others (%d)"))
 770     (recentf-arrange-by-rule l)))
 771
 772 (defun recentf-build-dir-rules (l)
 773   "Convert directories in menu-elements L to menu filter rules.
 774 Rules obey `recentf-arrange-rules' format."
 775   (let (dirs)
 776     (mapcar #'(lambda (e)
 777                 (let ((dir (file-name-directory
 778                             (recentf-menu-element-value e))))
 779                   (or (recentf-string-member dir dirs)
 780                       (push dir dirs))))
 781             l)
 782     (mapcar #'(lambda (d)
 783                 (cons (concat d " (%d)")
 784                       (concat "\\`" d)))
 785             (nreverse (sort dirs 'recentf-string-lessp)))))
 786
 787 (defun recentf-file-name-nondir (l)
 788   "Filter the list of menu-elements L to show filenames sans directory.
 789 This simplified version of `recentf-show-basenames' does not handle
 790 duplicates.  It is used by `recentf-arrange-by-dir' as its
 791 `recentf-arrange-by-rule-subfilter'."
 792   (mapcar #'(lambda (e)
 793               (recentf-make-menu-element
 794                (file-name-nondirectory (recentf-menu-element-value e))
 795                (recentf-menu-element-value e)))
 796           l))
 797
 798 (defun recentf-arrange-by-dir (l)
 799   "Split the list of menu-elements L into sub-menus by directory."
 800   (let ((recentf-arrange-rules (recentf-build-dir-rules l))
 801         (recentf-arrange-by-rule-subfilter 'recentf-file-name-nondir)
 802         recentf-arrange-by-rule-others)
 803     (nreverse (recentf-arrange-by-rule l))))
 804 \f
 805 ;;; Ring of menu filters
 806 ;;
 807 (defvar recentf-filter-changer-state nil
 808   "Used by `recentf-filter-changer' to hold its state.")
 809
 810 (defcustom recentf-filter-changer-alist
 811   '(
 812     (recentf-arrange-by-mode . "*Files by Mode*")
 813     (recentf-arrange-by-dir  . "*Files by Directory*")
 814     (recentf-arrange-by-rule . "*Files by User Rule*")
 815     )
 816   "*List of filters managed by `recentf-filter-changer'.
 817 Each filter is defined by a pair (FUNCTION . LABEL), where FUNCTION is
 818 the filter function, and LABEL is the menu item displayed to select
 819 that filter."
 820   :group 'recentf-filters
 821   :type '(repeat (cons function string))
 822   :set (lambda (variable value)
 823          (setq recentf-filter-changer-state nil)
 824          (recentf-menu-customization-changed variable value)))
 825
 826 (defun recentf-filter-changer-goto-next ()
 827   "Go to the next filter available.
 828 See `recentf-filter-changer'."
 829   (setq recentf-filter-changer-state (cdr recentf-filter-changer-state))
 830   (recentf-clear-data))
 831
 832 (defsubst recentf-filter-changer-get-current ()
 833   "Get the current filter available.
 834 See `recentf-filter-changer'."
 835   (unless recentf-filter-changer-state
 836     (setq recentf-filter-changer-state recentf-filter-changer-alist))
 837   (car recentf-filter-changer-state))
 838
 839 (defsubst recentf-filter-changer-get-next ()
 840   "Get the next filter available.
 841 See `recentf-filter-changer'."
 842   ;; At this point the current filter is the first element of
 843   ;; `recentf-filter-changer-state'.
 844   (car (or (cdr recentf-filter-changer-state)
 845            ;; There is no next element in
 846            ;; `recentf-filter-changer-state', so loop back to the
 847            ;; first element of `recentf-filter-changer-alist'.
 848            recentf-filter-changer-alist)))
 849
 850 (defun recentf-filter-changer (l)
 851   "Manage a ring of menu filters.
 852 `recentf-filter-changer-alist' defines the filters in the ring.
 853 Filtering of L is delegated to the current filter in the ring.  A
 854 filter menu item is displayed allowing to dynamically activate the
 855 next filter in the ring.  If the filter ring is empty, L is left
 856 unchanged."
 857   (let ((filter (recentf-filter-changer-get-current)))
 858     (when filter
 859       (setq l (recentf-apply-menu-filter (car filter) l)
 860             filter (recentf-filter-changer-get-next))
 861       (when filter
 862         (setq recentf-menu-filter-commands
 863               (list (vector (cdr filter)
 864                             '(recentf-filter-changer-goto-next)
 865                             t)))))
 866     l))
 867 \f
 868 ;;; Common dialog stuff
 869 ;;
 870 (defun recentf-cancel-dialog (&rest ignore)
 871   "Cancel the current dialog.
 872 Used internally by recentf dialogs.
 873 IGNORE arguments."
 874   (interactive)
 875   (kill-buffer (current-buffer))
 876   (message "Dialog canceled"))
 877
 878 (defvar recentf-dialog-mode-map
 879   (let ((km (make-sparse-keymap)))
 880     (define-key km "q" 'recentf-cancel-dialog)
 881     (define-key km [down-mouse-1] 'widget-button-click)
 882     (set-keymap-parent km widget-keymap)
 883     km)
 884   "Keymap used in recentf dialogs.")
 885
 886 (defun recentf-dialog-mode ()
 887   "Major mode of recentf dialogs.
 888
 889 \\{recentf-dialog-mode-map}"
 890   (interactive)
 891   (setq major-mode 'recentf-dialog-mode)
 892   (setq mode-name "recentf-dialog")
 893   (use-local-map recentf-dialog-mode-map))
 894 \f
 895 ;;; Hooks
 896 ;;
 897 (defun recentf-track-opened-file ()
 898   "Insert the name of the file just opened or written into the recent list."
 899   (and buffer-file-name
 900        (recentf-add-file buffer-file-name))
 901   ;; Must return nil because it is run from `write-file-functions'.
 902   nil)
 903
 904 (defun recentf-track-closed-file ()
 905   "Update the recent list when a buffer is killed.
 906 That is, remove a non readable file from the recent list, if
 907 `recentf-keep-non-readable-files-flag' is nil."
 908   (and buffer-file-name
 909        (not recentf-keep-non-readable-files-flag)
 910        (recentf-remove-if-non-readable buffer-file-name)))
 911
 912 (defun recentf-update-menu ()
 913   "Update the recentf menu from the current recent list."
 914   (let ((cache (cons default-directory recentf-list)))
 915     ;; Does nothing, if nothing has changed.
 916     (unless (equal recentf-data-cache cache)
 917       (setq recentf-data-cache cache)
 918       (condition-case err
 919           (easy-menu-change recentf-menu-path
 920                             recentf-menu-title
 921                             (recentf-make-menu-items)
 922                             recentf-menu-before)
 923         (error
 924          (message "recentf update menu failed: %s"
 925                   (error-message-string err)))))))
 926
 927 (defconst recentf-used-hooks
 928   '(
 929     (find-file-hook       recentf-track-opened-file)
 930     (write-file-functions recentf-track-opened-file)
 931     (kill-buffer-hook     recentf-track-closed-file)
 932     (menu-bar-update-hook recentf-update-menu)
 933     (kill-emacs-hook      recentf-save-list)
 934     )
 935   "Hooks used by recentf.")
 936
 937 (defsubst recentf-enabled-p ()
 938   "Return non-nil if recentf mode is currently enabled."
 939   (memq 'recentf-update-menu menu-bar-update-hook))
 940 \f
 941 ;;; Commands
 942 ;;
 943 (defvar recentf-edit-selected-items nil
 944   "List of files to be deleted from the recent list.
 945 Used internally by `recentf-edit-list'.")
 946
 947 (defun recentf-edit-list-action (widget &rest ignore)
 948   "Checkbox WIDGET action that toogles a file selection.
 949 Used internally by `recentf-edit-list'.
 950 IGNORE other arguments."
 951   (let ((value (widget-get widget ':tag)))
 952     ;; if value is already in the selected items
 953     (if (memq value recentf-edit-selected-items)
 954         ;; then remove it
 955         (progn
 956           (setq recentf-edit-selected-items
 957                 (delq value recentf-edit-selected-items))
 958           (message "%s removed from selection" value))
 959       ;; else add it
 960       (push value recentf-edit-selected-items)
 961       (message "%s added to selection" value))))
 962
 963 (defun recentf-edit-list ()
 964   "Show a dialog buffer to edit the recent list.
 965 That is to select files to be deleted from the recent list."
 966   (interactive)
 967   (with-current-buffer
 968       (get-buffer-create (format "*%s - Edit list*" recentf-menu-title))
 969     (switch-to-buffer (current-buffer))
 970     ;; Cleanup buffer
 971     (kill-all-local-variables)
 972     (let ((inhibit-read-only t)
 973           (ol (overlay-lists)))
 974       (erase-buffer)
 975       ;; Delete all the overlays.
 976       (mapc 'delete-overlay (car ol))
 977       (mapc 'delete-overlay (cdr ol)))
 978     (setq recentf-edit-selected-items nil)
 979     ;; Insert the dialog header
 980     (widget-insert
 981      "\
 982 Select the files to be deleted from the recent list.\n\n\
 983 Click on Ok to update the list. \
 984 Click on Cancel or type \"q\" to quit.\n")
 985     ;; Insert the list of files as checkboxes
 986     (dolist (item recentf-list)
 987       (widget-create
 988        'checkbox
 989        :value nil                       ; unselected checkbox
 990        :format "\n %[%v%]  %t"
 991        :tag item
 992        :notify 'recentf-edit-list-action))
 993     (widget-insert "\n\n")
 994     ;; Insert the Ok button
 995     (widget-create
 996      'push-button
 997      :notify (lambda (&rest ignore)
 998                (if recentf-edit-selected-items
 999                    (let ((i 0))
1000                      (kill-buffer (current-buffer))
1001                      (dolist (e recentf-edit-selected-items)
1002                        (setq recentf-list (delq e recentf-list)
1003                              i (1+ i)))
1004                      (message "%S file(s) removed from the list" i))
1005                  (message "No file selected")))
1006      "Ok")
1007     (widget-insert " ")
1008     ;; Insert the Cancel button
1009     (widget-create
1010      'push-button
1011      :notify 'recentf-cancel-dialog
1012      "Cancel")
1013     (recentf-dialog-mode)
1014     (widget-setup)
1015     (goto-char (point-min))))
1016
1017 (defun recentf-open-files-action (widget &rest ignore)
1018   "Button WIDGET action that open a file.
1019 Used internally by `recentf-open-files'.
1020 IGNORE other arguments."
1021   (kill-buffer (current-buffer))
1022   (funcall recentf-menu-action (widget-value widget)))
1023
1024 (defvar recentf-open-files-item-shift ""
1025   "Amount of space to shift right sub-menu items.
1026 Used internally by `recentf-open-files'.")
1027
1028 (defun recentf-open-files-item (menu-element)
1029   "Insert an item widget for MENU-ELEMENT in the current dialog buffer.
1030 Used internally by `recentf-open-files'."
1031   (let ((item (car menu-element))
1032         (file (cdr menu-element)))
1033     (if (consp file)               ; This is a sub-menu
1034         (let* ((shift recentf-open-files-item-shift)
1035                (recentf-open-files-item-shift (concat shift "  ")))
1036           (widget-create
1037            'item
1038            :tag item
1039            :sample-face 'bold
1040            :format (concat shift "%{%t%}:\n"))
1041           (mapc 'recentf-open-files-item file)
1042           (widget-insert "\n"))
1043       (widget-create
1044        'push-button
1045        :button-face 'default
1046        :tag item
1047        :help-echo (concat "Open " file)
1048        :format (concat recentf-open-files-item-shift "%[%t%]")
1049        :notify 'recentf-open-files-action
1050        file)
1051       (widget-insert "\n"))))
1052
1053 (defun recentf-open-files (&optional files buffer-name)
1054   "Show a dialog buffer to open a recent file.
1055 If optional argument FILES is non-nil, it specifies the list of
1056 recently-opened files to choose from.  It is the whole recent list
1057 otherwise.
1058 If optional argument BUFFER-NAME is non-nil, it specifies which buffer
1059 name to use for the interaction.  It is \"*`recentf-menu-title'*\" by
1060 default."
1061   (interactive)
1062   (unless files
1063     (setq files recentf-list))
1064   (unless buffer-name
1065     (setq buffer-name (format "*%s*" recentf-menu-title)))
1066   (with-current-buffer (get-buffer-create buffer-name)
1067     (switch-to-buffer (current-buffer))
1068     ;; Cleanup buffer
1069     (kill-all-local-variables)
1070     (let ((inhibit-read-only t)
1071           (ol (overlay-lists)))
1072       (erase-buffer)
1073       ;; Delete all the overlays.
1074       (mapc 'delete-overlay (car ol))
1075       (mapc 'delete-overlay (cdr ol)))
1076     ;; Insert the dialog header
1077     (widget-insert "Click on a file to open it. ")
1078     (widget-insert "Click on Cancel or type \"q\" to quit.\n\n" )
1079     ;; Insert the list of files as buttons
1080     (let ((recentf-open-files-item-shift ""))
1081       (mapc 'recentf-open-files-item
1082             (recentf-apply-menu-filter
1083              recentf-menu-filter
1084              (mapcar 'recentf-make-default-menu-element files))))
1085     (widget-insert "\n")
1086     ;; Insert the Cancel button
1087     (widget-create
1088      'push-button
1089      :notify 'recentf-cancel-dialog
1090      "Cancel")
1091     (recentf-dialog-mode)
1092     (widget-setup)
1093     (goto-char (point-min))))
1094
1095 (defun recentf-open-more-files ()
1096   "Show a dialog buffer to open a recent file that is not in the menu."
1097   (interactive)
1098   (recentf-open-files (nthcdr recentf-max-menu-items recentf-list)
1099                       (format "*%s - More*" recentf-menu-title)))
1100
1101 (defconst recentf-save-file-header
1102   ";;; Automatically generated by `recentf' on %s.\n"
1103   "Header to be written into the `recentf-save-file'.")
1104
1105 (defun recentf-save-list ()
1106   "Save the recent list.
1107 Write data into the file specified by `recentf-save-file'."
1108   (interactive)
1109   (with-temp-file (expand-file-name recentf-save-file)
1110     (erase-buffer)
1111     (insert (format recentf-save-file-header (current-time-string)))
1112     (recentf-dump-variable 'recentf-list recentf-max-saved-items)
1113     (recentf-dump-variable 'recentf-filter-changer-state)
1114     nil))
1115
1116 (defun recentf-load-list ()
1117   "Load a previously saved recent list.
1118 Read data from the file specified by `recentf-save-file'."
1119   (interactive)
1120   (let ((file (expand-file-name recentf-save-file)))
1121     (when (file-readable-p file)
1122       (load-file file))))
1123
1124 (defun recentf-cleanup ()
1125   "Remove all non-readable and excluded files from the recent list."
1126   (interactive)
1127   (message "Cleaning up the recentf list...")
1128   (let (newlist)
1129     (dolist (f recentf-list)
1130       (if (and (recentf-include-p f) (file-readable-p f))
1131           (push f newlist)
1132         (message "File %s removed from the recentf list" f)))
1133     (setq recentf-list (nreverse newlist))
1134     (message "Cleaning up the recentf list...done")))
1135
1136 ;;;###autoload
1137 (define-minor-mode recentf-mode
1138   "Toggle recentf mode.
1139 With prefix argument ARG, turn on if positive, otherwise off.
1140 Returns non-nil if the new state is enabled.
1141
1142 When recentf mode is enabled, it maintains a menu for visiting files
1143 that were operated on recently."
1144   :global t
1145   :group 'recentf
1146   (unless (and recentf-mode (recentf-enabled-p))
1147     (if recentf-mode
1148         (recentf-load-list)
1149       (recentf-save-list))
1150     (recentf-auto-cleanup)
1151     (recentf-clear-data)
1152     (let ((hook-setup (if recentf-mode 'add-hook 'remove-hook)))
1153       (dolist (hook recentf-used-hooks)
1154         (apply hook-setup hook)))
1155     (run-hooks 'recentf-mode-hook)
1156     (when (interactive-p)
1157       (message "Recentf mode %sabled" (if recentf-mode "en" "dis"))))
1158   recentf-mode)
1159
1160 (provide 'recentf)
1161
1162 (run-hooks 'recentf-load-hook)
1163
1164 ;;; recentf.el ends here