X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/608a4502b9fa8f5681368657fba5d5fd0fa46817..7e31acf6b81fdce7258077645bc239767c484841:/lisp/files.el diff --git a/lisp/files.el b/lisp/files.el index 5883c8c348..34c66bbd1d 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -4207,15 +4207,22 @@ FILENAME defaults to `buffer-file-name'." (defcustom make-backup-file-name-function #'make-backup-file-name--default-function - "A function to use instead of the default `make-backup-file-name'. + "A function that `make-backup-file-name' uses to create backup file names. +The function receives a single argument, the original file name. -This could be buffer-local to do something special for specific -files. If you define it, you may need to change `backup-file-name-p' -and `file-name-sans-versions' too. +If you change this, you may need to change `backup-file-name-p' and +`file-name-sans-versions' too. + +You could make this buffer-local to do something special for specific files. + +For historical reasons, a value of nil means to use the default function. +This should not be relied upon. See also `backup-directory-alist'." + :version "24.4" ; nil -> make-backup-file-name--default-function :group 'backup - :type '(function :tag "Your function")) + :type '(choice (const :tag "Deprecated way to get the default function" nil) + (function :tag "Function"))) (defcustom backup-directory-alist nil "Alist of filename patterns and backup directory names. @@ -4272,20 +4279,17 @@ Checks for files in `temporary-file-directory', (defun make-backup-file-name (file) "Create the non-numeric backup file name for FILE. -Normally this will just be the file's name with `~' appended. -Customization hooks are provided as follows. - -The value of `make-backup-file-name-function' should be a function which -will be called with FILE as its argument; the resulting name is used. - -By default, a match for FILE is sought in `backup-directory-alist'; see -the documentation of that variable. If the directory for the backup -doesn't exist, it is created." +This calls the function that `make-backup-file-name-function' specifies, +with a single argument FILE." (funcall (or make-backup-file-name-function #'make-backup-file-name--default-function) file)) (defun make-backup-file-name--default-function (file) + "Default function for `make-backup-file-name'. +Normally this just returns FILE's name with `~' appended. +It searches for a match for FILE in `backup-directory-alist'. +If the directory for the backup doesn't exist, it is created." (if (and (eq system-type 'ms-dos) (not (msdos-long-file-names))) (let ((fn (file-name-nondirectory file))) @@ -4297,7 +4301,8 @@ doesn't exist, it is created." (concat (make-backup-file-name-1 file) "~"))) (defun make-backup-file-name-1 (file) - "Subroutine of `make-backup-file-name' and `find-backup-file-name'." + "Subroutine of `make-backup-file-name--default-function'. +The function `find-backup-file-name' also uses this." (let ((alist backup-directory-alist) elt backup-directory abs-backup-directory) (while alist @@ -4374,8 +4379,8 @@ the index in the name where the version number begins." Value is a list whose car is the name for the backup file and whose cdr is a list of old versions to consider deleting now. If the value is nil, don't make a backup. -Uses `backup-directory-alist' in the same way as does -`make-backup-file-name'." +Uses `backup-directory-alist' in the same way as +`make-backup-file-name--default-function' does." (let ((handler (find-file-name-handler fn 'find-backup-file-name))) ;; Run a handler for this function so that ange-ftp can refuse to do it. (if handler @@ -5312,28 +5317,41 @@ comparison." (put 'revert-buffer-function 'permanent-local t) (defvar revert-buffer-function #'revert-buffer--default - "Function to use to revert this buffer, or nil to do the default. + "Function to use to revert this buffer. The function receives two arguments IGNORE-AUTO and NOCONFIRM, which are the arguments that `revert-buffer' received. It also has access to the `preserve-modes' argument of `revert-buffer' -via the `revert-buffer-preserve-modes' dynamic variable.") +via the `revert-buffer-preserve-modes' dynamic variable. + +For historical reasons, a value of nil means to use the default function. +This should not be relied upon.") (put 'revert-buffer-insert-file-contents-function 'permanent-local t) (defvar revert-buffer-insert-file-contents-function #'revert-buffer-insert-file-contents--default-function "Function to use to insert contents when reverting this buffer. -Gets two args, first the nominal file name to use, -and second, t if reading the auto-save file. +The function receives two arguments: the first the nominal file name to use; +the second is t if reading the auto-save file. + +The function is responsible for updating (or preserving) point. -The function you specify is responsible for updating (or preserving) point.") +For historical reasons, a value of nil means to use the default function. +This should not be relied upon.") (defun buffer-stale--default-function (&optional _noconfirm) + "Default function to use for `buffer-stale-function'. +This function ignores its argument. +This returns non-nil if the current buffer is visiting a readable file +whose modification time does not match that of the buffer. + +This function only handles buffers that are visiting files. +Non-file buffers need a custom function" (and buffer-file-name (file-readable-p buffer-file-name) (not (verify-visited-file-modtime (current-buffer))))) (defvar buffer-stale-function #'buffer-stale--default-function - "Function to check whether a non-file buffer needs reverting. + "Function to check whether a buffer needs reverting. This should be a function with one optional argument NOCONFIRM. Auto Revert Mode passes t for NOCONFIRM. The function should return non-nil if the buffer should be reverted. A return value of @@ -5346,13 +5364,16 @@ non-nil if the buffer is going to be reverted without asking the user. In such situations, one has to be careful with potentially time consuming operations. +For historical reasons, a value of nil means to use the default function. +This should not be relied upon. + For more information on how this variable is used by Auto Revert mode, see Info node `(emacs)Supporting additional buffers'.") (defvar before-revert-hook nil "Normal hook for `revert-buffer' to run before reverting. -If `revert-buffer-function' is used to override the normal revert -mechanism, this hook is not used.") +The function `revert-buffer--default' runs this. +A customized `revert-buffer-function' need not run this hook.") (defvar after-revert-hook nil "Normal hook for `revert-buffer' to run after reverting. @@ -5360,12 +5381,11 @@ Note that the hook value that it runs is the value that was in effect before reverting; that makes a difference if you have buffer-local hook functions. -If `revert-buffer-function' is used to override the normal revert -mechanism, this hook is not used.") +The function `revert-buffer--default' runs this. +A customized `revert-buffer-function' need not run this hook.") (defvar revert-buffer-in-progress-p nil - "Non-nil if a `revert-buffer' operation is in progress, nil otherwise. -This is true even if a `revert-buffer-function' is being used.") + "Non-nil if a `revert-buffer' operation is in progress, nil otherwise.") (defvar revert-buffer-internal-hook) @@ -5402,12 +5422,10 @@ the files modes. Normally we reinitialize them using `normal-mode'. This function binds `revert-buffer-in-progress-p' non-nil while it operates. -If the value of `revert-buffer-function' is non-nil, it is called to -do all the work for this command. Otherwise, the hooks -`before-revert-hook' and `after-revert-hook' are run at the beginning -and the end, and if `revert-buffer-insert-file-contents-function' is -non-nil, it is called instead of rereading visited file contents." - +This function calls the function that `revert-buffer-function' specifies +to do the work, with arguments IGNORE-AUTO and NOCONFIRM. +The default function runs the hooks `before-revert-hook' and +`after-revert-hook'." ;; I admit it's odd to reverse the sense of the prefix argument, but ;; there is a lot of code out there which assumes that the first ;; argument should be t to avoid consulting the auto-save file, and @@ -5419,7 +5437,19 @@ non-nil, it is called instead of rereading visited file contents." (revert-buffer-preserve-modes preserve-modes)) (funcall (or revert-buffer-function #'revert-buffer--default) ignore-auto noconfirm))) + (defun revert-buffer--default (ignore-auto noconfirm) + "Default function for `revert-buffer'. +The arguments IGNORE-AUTO and NOCONFIRM are as described for `revert-buffer'. +Runs the hooks `before-revert-hook' and `after-revert-hook' at the +start and end. + +Calls `revert-buffer-insert-file-contents-function' to reread the +contents of the visited file, with two arguments: the first is the file +name, the second is non-nil if reading an auto-save file. + +This function only handles buffers that are visiting files. +Non-file buffers need a custom function." (with-current-buffer (or (buffer-base-buffer (current-buffer)) (current-buffer)) (let* ((auto-save-p (and (not ignore-auto) @@ -5473,6 +5503,10 @@ non-nil, it is called instead of rereading visited file contents." t))))) (defun revert-buffer-insert-file-contents--default-function (file-name auto-save-p) + "Default function for `revert-buffer-insert-file-contents-function'. +The function `revert-buffer--default' calls this. +FILE-NAME is the name of the file. AUTO-SAVE-P is non-nil if this is +an auto-save file." (cond ((not (file-exists-p file-name)) (error (if buffer-file-number