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