1 ;; recentf.el --- setup a menu of recently opened files
3 ;; Copyright (C) 1999 Free Software Foundation, Inc.
5 ;; Author: David Ponce <david.ponce@wanadoo.fr>
6 ;; Created: July 19 1999
7 ;; Keywords: customization
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software; you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation; either version 2, or (at your option)
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs; see the file COPYING. If not, write to the
23 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
24 ;; Boston, MA 02111-1307, USA.
35 (defconst recentf-save-file-header
36 ";;; Automatically generated by `recentf' on %s.\n"
37 "Header to be written into the `recentf-save-file'.")
39 (defvar recentf-list nil
40 "List of recently opened files.")
42 (defvar recentf-update-menu-p t
43 "Non-nil if the recentf menu must be updated.")
45 (defvar recentf-initialized-p nil
46 "Non-nil if recentf already initialized.")
48 ;; IMPORTANT: This function must be defined before the following defcustoms
49 ;; because it is used in their :set clause. To avoid byte-compiler warnings
50 ;; the `symbol-value' function is used to access the `recentf-menu-path'
51 ;; and `recentf-menu-title' values.
52 (defun recentf-menu-customization-changed (sym val)
53 "Function called when menu customization has changed.
54 It removes the recentf menu and forces its complete redrawing."
55 (when recentf-initialized-p
56 (easy-menu-remove-item nil
57 (symbol-value 'recentf-menu-path)
58 (symbol-value 'recentf-menu-title))
59 (setq recentf-update-menu-p t))
60 (custom-set-default sym val))
63 "Maintain a menu of recently opened files."
67 (defcustom recentf-max-saved-items 20
68 "*Maximum number of items saved to `recentf-save-file'."
72 (defcustom recentf-save-file (expand-file-name "~/.recentf")
73 "*File to save `recentf-list' into."
77 (defcustom recentf-exclude nil
78 "*List of regexps for filenames excluded from `recentf-list'."
80 :type '(repeat regexp))
82 (defcustom recentf-menu-title "Open Recent"
83 "*Name of the recentf menu."
86 :set 'recentf-menu-customization-changed)
88 (defcustom recentf-menu-path '("files")
89 "*Path where to add the recentf menu.
90 If nil add it at top-level (see also `easy-menu-change')."
92 :type '(choice (const :tag "Top Level" nil)
93 (sexp :tag "Menu Path"))
94 :set 'recentf-menu-customization-changed)
96 (defcustom recentf-menu-before "open-file"
97 "*Name of the menu before which the recentf menu will be added.
98 If nil add it at end of menu (see also `easy-menu-change')."
100 :type '(choice (string :tag "Name")
101 (const :tag "Last" nil))
102 :set 'recentf-menu-customization-changed)
104 (defcustom recentf-menu-action 'recentf-find-file
105 "*Function to invoke with a filename item of the recentf menu.
106 The default action `recentf-find-file' calls `find-file' to edit an
107 existing file. If the file does not exist or is not readable, it is
108 not edited and its name is removed from `recentf-list'. You can use
109 `find-file' instead to open non-existing files and keep them in the
110 list of recently opened files."
113 :set 'recentf-menu-customization-changed)
115 (defcustom recentf-max-menu-items 10
116 "*Maximum number of items in the recentf menu."
119 :set 'recentf-menu-customization-changed)
121 (defcustom recentf-menu-filter nil
122 "*Function used to filter files displayed in the recentf menu.
123 Nil means no filter. The following functions are predefined:
125 - - `recentf-sort-ascending' to sort menu items in ascending order.
126 - - `recentf-sort-descending' to sort menu items in descending order.
128 The filter function is called with one argument, the list of filenames to be
129 displayed in the menu and must return a new list of filenames."
132 :set 'recentf-menu-customization-changed)
134 (defcustom recentf-menu-append-commands-p t
135 "*If not-nil command items are appended to the menu."
138 :set 'recentf-menu-customization-changed)
140 (defcustom recentf-keep-non-readable-files-p nil
141 "*If nil (default), non-readable files are not kept in `recentf-list'."
145 (defcustom recentf-keep-non-readable-files-p nil
146 "*If nil (default), non-readable files are not kept in `recentf-list'."
150 :initialize 'custom-initialize-default
151 :set (lambda (sym val)
153 (remove-hook 'kill-buffer-hook 'recentf-remove-file-hook)
154 (add-hook 'kill-buffer-hook 'recentf-remove-file-hook))
155 (custom-set-default sym val))))
157 (defcustom recentf-mode nil
158 "Toggle recentf mode.
159 When recentf mode is enabled, it maintains a menu for visiting files that
160 were operated on recently.
161 Setting this variable directly does not take effect;
162 use either \\[customize] or the function `recentf-mode'."
163 :set (lambda (symbol value)
164 (recentf-mode (or value 0)))
165 :initialize 'custom-initialize-default
170 (defcustom recentf-load-hook nil
171 "*Normal hook run at end of loading the `recentf' package."
176 (defun recentf-mode (&optional arg)
177 "Toggle recentf mode.
178 With prefix ARG, turn recentf mode on if and only if ARG is positive.
179 Returns the new status of recentf mode (non-nil means on).
181 When recentf mode is enabled, it maintains a menu for visiting files that
182 were operated on recently."
185 (> (prefix-numeric-value arg) 0)
186 (not recentf-mode))))
188 (unless recentf-initialized-p
189 (setq recentf-initialized-p t)
190 (if (file-readable-p recentf-save-file)
191 (load-file recentf-save-file))
192 (setq recentf-update-menu-p t)
193 (add-hook 'find-file-hooks 'recentf-add-file-hook)
194 (add-hook 'write-file-hooks 'recentf-add-file-hook)
195 ;; (add-hook 'activate-menubar-hook 'recentf-update-menu-hook)
196 (add-hook 'menu-bar-update-hook 'recentf-update-menu-hook)
197 (add-hook 'kill-emacs-hook 'recentf-save-list))
198 (when recentf-initialized-p
199 (setq recentf-initialized-p nil)
201 (easy-menu-remove-item nil recentf-menu-path recentf-menu-title)
202 (remove-hook 'find-file-hooks 'recentf-add-file-hook)
203 (remove-hook 'write-file-hooks 'recentf-add-file-hook)
204 ;; (remove-hook 'activate-menubar-hook 'recentf-update-menu-hook)
205 (remove-hook 'menu-bar-update-hook 'recentf-update-menu-hook)
206 (remove-hook 'kill-emacs-hook 'recentf-save-list)))
207 (setq recentf-mode on-p)))
209 (defun recentf-add-file-hook ()
210 "Insert the name of the file just opened or written into `recentf-list'."
211 (and buffer-file-name (recentf-add-file buffer-file-name))
214 (defun recentf-remove-file-hook ()
215 "When a buffer is killed remove a non readable file from `recentf-list'."
216 (and buffer-file-name (recentf-remove-if-non-readable buffer-file-name))
219 (defun recentf-update-menu-hook ()
220 "Update the recentf menu from the current `recentf-list'."
221 (when recentf-update-menu-p
224 (easy-menu-change recentf-menu-path
226 (recentf-make-menu-items)
228 (setq recentf-update-menu-p nil))
232 (defun recentf-save-list ()
233 "Save the current `recentf-list' to the file `recentf-save-file'."
235 (let ((saved-list (recentf-elements recentf-max-saved-items)))
238 (insert (format recentf-save-file-header (current-time-string)))
239 (insert "(setq recentf-list\n '(\n")
241 (insert (format " %S\n" e)))
244 (if (file-writable-p recentf-save-file)
245 (write-region (point-min) (point-max) recentf-save-file))
246 (kill-buffer (current-buffer))))
249 (defvar recentf-edit-selected-items nil
250 "Used by `recentf-edit-list' to hold the list of files to be deleted
251 from `recentf-list'.")
253 (defun recentf-edit-list-action (widget &rest ignore)
254 "Checkbox widget action used by `recentf-edit-list' to select/unselect a file."
255 (let ((value (widget-get widget ':tag)))
256 ;; if value is already in the selected items
257 (if (memq value recentf-edit-selected-items)
260 (setq recentf-edit-selected-items
261 (delq value recentf-edit-selected-items))
262 (message "%s removed from selection." value))
265 (setq recentf-edit-selected-items
266 (nconc (list value) recentf-edit-selected-items))
267 (message "%s added to selection." value)))))
270 (defun recentf-edit-list ()
271 "Allow the user to edit the files that are kept in the recent list."
273 (with-current-buffer (get-buffer-create (concat "*" recentf-menu-title " - Edit list*"))
274 (switch-to-buffer (current-buffer))
275 (kill-all-local-variables)
276 (let ((inhibit-read-only t))
278 (let ((all (overlay-lists)))
279 ;; Delete all the overlays.
280 (mapcar 'delete-overlay (car all))
281 (mapcar 'delete-overlay (cdr all)))
282 (setq recentf-edit-selected-items nil)
283 ;; Insert the dialog header
284 (widget-insert "Select the files to be deleted from the 'recentf-list'.\n\n")
285 (widget-insert "Click on Ok to update the list or on Cancel to quit.\n" )
286 ;; Insert the list of files as checkboxes
287 (mapcar '(lambda (item)
288 (widget-create 'checkbox
289 :value nil ; unselected checkbox
290 :format "\n %[%v%] %t"
292 :notify 'recentf-edit-list-action))
294 (widget-insert "\n\n")
295 ;; Insert the Ok button
296 (widget-create 'push-button
297 :notify (lambda (&rest ignore)
298 (if recentf-edit-selected-items
299 (progn (kill-buffer (current-buffer))
300 (mapcar '(lambda (item)
302 (delq item recentf-list)))
303 recentf-edit-selected-items)
304 (message "%S file(s) removed from the list"
305 (length recentf-edit-selected-items))
306 (setq recentf-update-menu-p t))
307 (message "No file selected.")))
310 ;; Insert the Cancel button
311 (widget-create 'push-button
312 :notify (lambda (&rest ignore)
313 (kill-buffer (current-buffer))
314 (message "Command canceled."))
316 (use-local-map widget-keymap)
320 (defun recentf-cleanup ()
321 "Remove all non-readable and excluded files from `recentf-list'."
325 (mapcar '(lambda (filename)
326 (and (file-readable-p filename)
327 (recentf-include-p filename)
330 (setq recentf-update-menu-p t))
332 (defun recentf-open-more-files-action (widget &rest ignore)
333 "Button widget action used by `recentf-open-more-files' to open a file."
334 (kill-buffer (current-buffer))
335 (funcall recentf-menu-action (widget-value widget)))
338 (defun recentf-open-more-files ()
339 "Allow the user to open files that are not in the menu."
341 (with-current-buffer (get-buffer-create (concat "*" recentf-menu-title " - More*"))
342 (switch-to-buffer (current-buffer))
343 (kill-all-local-variables)
344 (let ((inhibit-read-only t))
346 (let ((all (overlay-lists)))
347 ;; Delete all the overlays.
348 (mapcar 'delete-overlay (car all))
349 (mapcar 'delete-overlay (cdr all)))
350 ;; Insert the dialog header
351 (widget-insert "Click on a file to open it or on Cancel to quit.\n\n")
352 ;; Insert the list of files as buttons
353 (mapcar '(lambda (menu-element)
354 (let ((menu-item (car menu-element))
355 (file-path (cdr menu-element)))
356 (widget-create 'push-button
357 :button-face 'default
359 :help-echo (concat "Open " file-path)
361 :notify 'recentf-open-more-files-action
363 (widget-insert "\n")))
364 (funcall (or recentf-menu-filter 'identity)
365 (mapcar '(lambda (item) (cons item item))
366 (nthcdr recentf-max-menu-items recentf-list))))
368 ;; Insert the Cancel button
369 (widget-create 'push-button
370 :notify (lambda (&rest ignore)
371 (kill-buffer (current-buffer))
372 (message "Command canceled."))
374 (use-local-map widget-keymap)
377 (defvar recentf-menu-items-for-commands
378 (list ["Cleanup list" recentf-cleanup t]
379 ["Edit list..." recentf-edit-list t]
380 ["Save list now" recentf-save-list t]
381 (vector "Recentf Options..." '(customize-group "recentf") t))
382 "List of menu items for recentf commands.")
384 (defun recentf-make-menu-items ()
385 "Make menu items from `recentf-list'."
387 (mapcar '(lambda (entry)
388 (vector entry (list recentf-menu-action entry) t))
389 (funcall (or recentf-menu-filter 'identity)
390 (recentf-elements recentf-max-menu-items)))))
391 (append (or file-items (list ["No files" t nil]))
392 (and (< recentf-max-menu-items (length recentf-list))
393 (list ["More..." recentf-open-more-files t]))
394 (and recentf-menu-append-commands-p
395 (cons ["---" nil nil]
396 recentf-menu-items-for-commands)))))
398 (defun recentf-add-file (filename)
399 "Add or move FILENAME at the beginning of `recentf-list'.
400 Does nothing if FILENAME matches one of the `recentf-exclude' regexps."
401 (when (recentf-include-p filename)
402 (setq recentf-list (cons filename (delete filename recentf-list)))
403 (setq recentf-update-menu-p t)))
405 (defun recentf-remove-if-non-readable (filename)
406 "Remove FILENAME from `recentf-list' if not readable."
407 (unless (file-readable-p filename)
408 (setq recentf-list (delete filename recentf-list))
409 (setq recentf-update-menu-p t)))
411 (defun recentf-find-file (filename)
412 "Edit file FILENAME using `find-file'.
413 If FILENAME is not readable it is removed from `recentf-list'."
414 (if (file-readable-p filename)
417 (message "File `%s' not found." filename)
418 (setq recentf-list (delete filename recentf-list))
419 (setq recentf-update-menu-p t))))
421 (defun recentf-include-p (filename)
422 "Return t if FILENAME matches none of the `recentf-exclude' regexps."
423 (let ((rl recentf-exclude))
424 (while (and rl (not (string-match (car rl) filename)))
428 (defun recentf-elements (n)
429 "Return a list of the first N elements of `recentf-list'."
430 (let ((lh nil) (l recentf-list))
431 (while (and l (> n 0))
432 (setq lh (cons (car l) lh))
437 (defun recentf-sort-ascending (l)
438 "Sort the list of strings L in ascending order."
439 (sort l '(lambda (e1 e2) (string-lessp e1 e2))))
441 (defun recentf-sort-descending (l)
442 "Sort the list of strings L in descending order."
443 (sort l '(lambda (e1 e2) (string-lessp e2 e1))))
447 (run-hooks 'recentf-load-hook)
449 ;;; recentf.el ends here.