emacs/lisp/recentf.el

10 ;; This file is part of GNU Emacs.
23 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
73 (defcustom recentf-save-file "~/.recentf"
76   :type 'file
77   :initialize 'custom-initialize-default
80            (custom-set-default symbol value)
85 (defcustom recentf-save-file-modes 384 ;; 0600
86   "Mode bits of recentf save file, as an integer, or nil.
87 If non-nil, after writing `recentf-save-file', set its mode bits to
88 this value.  By default give R/W access only to the user who owns that
89 file.  See also the function `set-file-modes'."
104   '(file-readable-p)
110 The default is to keep readable files.
113 `file-remote-p' predicate in front of this list to keep remote file
126         (set-default variable value)
128     (set-default variable value)))
152 (defcustom recentf-menu-action 'find-file
154 The default is to call `find-file' to edit the selected file."
186     Show filenames relative to `default-directory'.
237     Cleanup when turning the mode on (default).
260          (set-default variable value)
265 (defcustom recentf-initialize-file-name-history t
266   "*Non-nil means to initialize `file-name-history' with the recent list.
267 If `file-name-history' is not empty, do nothing."
277   "Functions to post process recent file names.
278 They are successively passed a file name to transform it."
284             (const file-truename)
285             (const abbreviate-file-name)
288 (defcustom recentf-show-file-shortcuts-flag t
291 used as shortcuts to open the Nth file."
299   (memq system-type '(vax-vms windows-nt cygwin))
337 specifies a maximum number of elements to insert.  By default insert
382 (defun recentf-apply-filename-handlers (name)
383   "Apply `recentf-filename-handlers' to file NAME.
384 Return the transformed file name, or NAME if any handler failed, or
388                 (filename name))
394       name))
396 (defsubst recentf-expand-file-name (name)
397   "Convert file NAME to absolute, and canonicalize it.
398 NAME is first passed to the function `expand-file-name', then to
400   (recentf-apply-filename-handlers (expand-file-name name)))
436 (defsubst recentf-add-file (filename)
438 Does nothing if the name satisfies any of the `recentf-exclude'
440   (setq filename (recentf-expand-file-name filename))
445   "Remove FILENAME from the recent list, if file is not kept.
449               (recentf-expand-file-name filename) recentf-list)))
456   (let ((d1 (file-name-directory f1))
457         (d2 (file-name-directory f2)))
459         (recentf-string-lessp (file-name-nondirectory f1)
460                               (file-name-nondirectory f2))
466 (defsubst recentf-digit-shortcut-command-name (n)
467   "Return a command name to open the Nth most recent file.
468 See also the command `recentf-open-most-recent-file'."
469   (intern (format "recentf-open-most-recent-file-%d" n)))
474       (let ((cmd (recentf-digit-shortcut-command-name k)))
479              (recentf-open-most-recent-file ,k)))
509 to the recent file list part of the menu.  Before calling a menu
519 the menu item string displayed.  MENU-VALUE is the file to be open
546 (defsubst recentf-make-default-menu-element (file)
547   "Make a new default menu element with FILE.
549   (recentf-make-menu-element file file))
552   "Return a list of the first N default menu elements from the recent list.
553 See also `recentf-make-default-menu-element'."
554   (mapcar 'recentf-make-default-menu-element
593          (file-items
603      (or file-items
605             :help "No recent file to open"
620 (defun recentf-menu-value-shortcut (name)
621   "Return a shortcut digit for file NAME.
622 Return nil if file NAME is not one of the ten more recent."
625       (if (string-equal name (nth i recentf-list))
641                 ;; If the file name is one of the ten more recent, use
645                     (recentf-digit-shortcut-command-name k)
695              (file-name-nondirectory (recentf-menu-element-value e1))
696              (file-name-nondirectory (recentf-menu-element-value e2))))))
704              (file-name-nondirectory (recentf-menu-element-value e2))
705              (file-name-nondirectory (recentf-menu-element-value e1))))))
729   (let (filtered-names filtered-list full name counters sufx)
732             name (file-name-nondirectory full))
733       (if (not (member name filtered-names))
734           (push name filtered-names)
736             (if (setq sufx (assoc name counters))
739               (push (cons name sufx) counters))
740           (setq sufx (file-name-directory full)))
741         (setq name (format "%s(%s)" name sufx)))
742       (push (recentf-make-menu-element name full) filtered-list))))
760 Filenames are relative to the `default-directory'."
763                      (rel (file-relative-name ful default-directory)))
823          (set-default variable value)))
825 (defun recentf-match-rule (file)
833       (while (and match (not (string-match (car match) file)))
836           (setq found (cons (caar rules) file))
844     (let (menus others menu file min count)
847         (setq file (recentf-menu-element-value elt)
848               menu (recentf-match-rule file))
896 (defun recentf-indirect-mode-rule (file)
898   (recentf-match-rule (substring file 0 (match-beginning 0))))
904         regexp rule-name rule rules)
915           (setq rule-name 'recentf-indirect-mode-rule))
917           (setq rule-name (symbol-name mode))
918           (if (string-match "\\(.*\\)-mode$" rule-name)
919               (setq rule-name (match-string 1 rule-name)))
920           (setq rule-name (concat rule-name " (%d)"))))
921         (setq rule (assoc rule-name rules))
924           (push (list rule-name regexp) rules))))
926     ;; to ensure the right file <-> mode association
935 (defun recentf-file-name-nondir (l)
942                (file-name-nondirectory (recentf-menu-element-value e))
946 (defun recentf-dir-rule (file)
948   (cons (file-name-directory file) file))
953         (recentf-arrange-by-rule-subfilter 'recentf-file-name-nondir)
977          (set-default variable value)))
1012 (defun recentf-track-opened-file ()
1013   "Insert the name of the file just opened or written into the recent list."
1014   (and buffer-file-name
1015        (recentf-add-file buffer-file-name))
1016   ;; Must return nil because it is run from `write-file-functions'.
1019 (defun recentf-track-closed-file ()
1021 That is, remove a non kept file from the recent list."
1022   (and buffer-file-name
1023        (recentf-remove-if-non-kept buffer-file-name)))
1027     (find-file-hook       recentf-track-opened-file)
1028     (write-file-functions recentf-track-opened-file)
1029     (kill-buffer-hook     recentf-track-closed-file)
1077 (defmacro recentf-dialog (name &rest forms)
1080   `(with-current-buffer (get-buffer-create ,name)
1098   "Toggle a file selection based on the checkbox WIDGET state.
1116         (message "%S file(s) removed from the list" i))
1117     (message "No file selected")))
1150 ;;; Open file dialog
1153   "Open the file stored in WIDGET's value when notified.
1182     ;; Represent a single file with a link widget
1186            :button-face default
1200            (when recentf-show-file-shortcuts-flag
1204               (mapcar 'recentf-make-default-menu-element
1209             (mapcar 'recentf-make-default-menu-element
1212 (defun recentf-open-files (&optional files buffer-name)
1213   "Show a dialog to open a recent file.
1216 If optional argument BUFFER-NAME is non-nil, it is a buffer name to
1220     (error "There is no recent file to open"))
1221   (recentf-dialog (or buffer-name (format "*%s*" recentf-menu-title))
1222     (widget-insert "Click on a file"
1223                    (if recentf-show-file-shortcuts-flag
1242   "Show a dialog to open a recent file that is not in the menu."
1247 (defun recentf-open-most-recent-file (&optional n)
1248   "Open the Nth most recent file.
1250 1 opens the most recent file, 2 the second most recent one, etc..
1251 0 opens the tenth most recent file."
1256    ((error "Recent file number out of range [0-9], %d" n)))
1257   (let ((file (nth (1- n) (or recentf--files-with-key recentf-list))))
1258     (unless file (error "Not that many recent files"))
1262     (funcall recentf-menu-action file)))
1267 (defconst recentf-save-file-header
1269   "Header to be written into the `recentf-save-file'.")
1271 (defconst recentf-save-file-coding-system
1272   (if (coding-system-p 'utf-8-emacs)
1275   "Coding system of the file `recentf-save-file'.")
1279 Write data into the file specified by `recentf-save-file'."
1284         (set-buffer-file-coding-system recentf-save-file-coding-system)
1285         (insert (format recentf-save-file-header (current-time-string)))
1290                 (format ";;; coding: %s\n" recentf-save-file-coding-system)
1292         (write-file (expand-file-name recentf-save-file))
1293         (when recentf-save-file-modes
1294           (set-file-modes recentf-save-file recentf-save-file-modes))
1301 Read data from the file specified by `recentf-save-file'.
1302 When `recentf-initialize-file-name-history' is non-nil, initialize an
1303 empty `file-name-history' with the recent list."
1305   (let ((file (expand-file-name recentf-save-file)))
1306     (when (file-readable-p file)
1307       (load-file file)
1308       (and recentf-initialize-file-name-history
1309            (not file-name-history)
1310            (setq file-name-history (mapcar 'abbreviate-file-name
1320       (setq f (recentf-expand-file-name f))