X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/fa78f71bdb803fd6ee2fd796a21b1a4ecb0a7c08..dc6a28319312fe81f7a1015e363174022313f0bd:/lisp/time-stamp.el diff --git a/lisp/time-stamp.el b/lisp/time-stamp.el index 7a04c72d07..a3f0d66be3 100644 --- a/lisp/time-stamp.el +++ b/lisp/time-stamp.el @@ -1,17 +1,20 @@ ;;; time-stamp.el --- Maintain last change time stamps in files edited by Emacs -;; Copyright 1989, 1993, 1994, 1995, 1997 Free Software Foundation, Inc. +;; Copyright 1989, 1993, 1994, 1995, 1997, 2000, 2001 +;;; Free Software Foundation, Inc. -;; Maintainer's Time-stamp: <1999-06-26 15:12:53 gildea> -;; Maintainer: Stephen Gildea +;; This file is part of GNU Emacs. + +;; Maintainer's Time-stamp: <2003-02-01 09:26:25 gildea> +;; Maintainer: Stephen Gildea ;; Keywords: tools -;; This file is free software; you can redistribute it and/or modify +;; GNU Emacs is free software; you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation; either version 2, or (at your option) ;; any later version. -;; This file is distributed in the hope that it will be useful, +;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. @@ -25,7 +28,7 @@ ;; A template in a file can be updated with a new time stamp when ;; you save the file. For example: -;; static char *ts = "sdmain.c Time-stamp: <1996-08-13 10:20:51 gildea>"; +;; static char *ts = "sdmain.c Time-stamp: <2001-08-13 10:20:51 gildea>"; ;; See the top of `time-stamp.el' for another example. ;; To use time-stamping, add this line to your .emacs file: @@ -47,7 +50,11 @@ The value may be a string or a list. Lists are supported only for backward compatibility; see variable `time-stamp-old-format-warn'. -A string is used verbatim except for character sequences beginning with %: +A string is used verbatim except for character sequences beginning +with %, as follows. The values of non-numeric formatted items depend +on the locale setting recorded in `system-time-locale' and +`locale-coding-system'. The examples here are for the default +\(`C') locale. %:a weekday name: `Monday'. %#A gives uppercase: `MONDAY' %3a abbreviated weekday: `Mon'. %3A gives uppercase: `MON' @@ -61,7 +68,7 @@ A string is used verbatim except for character sequences beginning with %: %#p `am' or `pm'. %P gives uppercase: `AM' or `PM' %02S seconds %w day number of week, Sunday is 0 -%02y 2-digit year: `97' %:y 4-digit year: `1997' +%02y 2-digit year: `03' %:y 4-digit year: `2003' %z time zone name: `est'. %Z gives uppercase: `EST' Non-date items: @@ -84,7 +91,8 @@ change in a future version. Therefore either a padding width should be specified, or the : modifier should be used to explicitly request the historical default." :type 'string - :group 'time-stamp) + :group 'time-stamp + :version "20.1") (defcustom time-stamp-active t "*Non-nil to enable time-stamping of buffers by \\[time-stamp]. @@ -94,27 +102,31 @@ See also the variable `time-stamp-warn-inactive'." :group 'time-stamp) (defcustom time-stamp-warn-inactive t - "Non-nil to have \\[time-stamp] warn if a buffer did not get time-stamped. -A warning is printed if `time-stamp-active' disables time stamping and the -buffer contains a template that would otherwise have been updated." + "Have \\[time-stamp] warn if a buffer did not get time-stamped. +If non-nil, a warning is displayed if `time-stamp-active' has +deactivated time stamping and the buffer contains a template that +otherwise would have been updated." :type 'boolean - :group 'time-stamp) + :group 'time-stamp + :version "19.29") (defcustom time-stamp-old-format-warn 'ask - "Action to take if `time-stamp-format' is an old-style list. + "Action if `time-stamp-format' is an old-style list. If `error', the format is not used. If `ask', the user is queried about using the time-stamp-format. If `warn', a warning is displayed. If nil, no notification is given." - :type '(choice (const :tag "No notification" nil) - (const :tag "Don't use the format" error) - (const ask) (const warn)) + :type '(choice (const :tag "Don't use the format" error) + (const ask) + (const warn) + (const :tag "No notification" nil)) :group 'time-stamp) (defcustom time-stamp-time-zone nil "If non-nil, a string naming the timezone to be used by \\[time-stamp]. Format is the same as that used by the environment variable TZ on your system." :type '(choice (const nil) string) - :group 'time-stamp) + :group 'time-stamp + :version "20.1") ;;; Do not change time-stamp-line-limit, time-stamp-start, @@ -166,7 +178,7 @@ do so in the local variables section of the time-stamped file itself.") (defvar time-stamp-inserts-lines nil ;Do not change! - "Whether time-stamp can change the number of lines in a file. + "Whether \\[time-stamp] can change the number of lines in a file. If nil, \\[time-stamp] skips as many lines as there are newlines in `time-stamp-format' before looking for the `time-stamp-end' pattern, thus it tries not to change the number of lines in the buffer. @@ -182,8 +194,8 @@ variables section of the time-stamped file itself.") (defvar time-stamp-count 1 ;Do not change! - "How many time stamp templates \\[time-stamp] will look for in a buffer. -The same time-stamp will be written in each case. + "How many templates \\[time-stamp] will look for in a buffer. +The same time stamp will be written in each case. Do not change `time-stamp-count' for yourself or you will be incompatible with other people's files! If you must change it for @@ -191,7 +203,7 @@ some application, do so in the local variables section of the time-stamped file itself.") -(defvar time-stamp-pattern "%%" ;Do not change! +(defvar time-stamp-pattern nil ;Do not change! "Convenience variable setting all `time-stamp' location and format values. This string has four parts, each of which is optional. These four parts set `time-stamp-line-limit', `time-stamp-start', @@ -200,21 +212,24 @@ for each of these variables for details. The first part is a number followed by a slash; the number sets the number of lines at the beginning (negative counts from end) of the file searched -for the time-stamp. The number and the slash may be omitted to use the +for the time stamp. The number and the slash may be omitted to use the normal value. The second part is a regexp identifying the pattern preceding the time stamp. This part may be omitted to use the normal pattern. -The third part specifies the format of the time-stamp inserted. See +The third part specifies the format of the time stamp inserted. See the documentation for `time-stamp-format' for details. Specify this part as \"%%\" to use the normal format. The fourth part is a regexp identifying the pattern following the time stamp. This part may be omitted to use the normal pattern. -As an example, the default behavior can be specified something like this: -\"8/Time-stamp: [\\\"<]%:y-%02m-%02d %02H:%02M:%02S %u[\\\">]\" +Examples: +\"-10/\" +\"-9/^Last modified: %%$\" +\"@set Time-stamp: %:b %:d, %:y$\" +\"newcommand{\\\\\\\\timestamp}{%%}\" Do not change `time-stamp-pattern' for yourself or you will be incompatible with other people's files! Set it only in the local variables section @@ -233,7 +248,7 @@ look like one of the following: Time-stamp: <> Time-stamp: \" \" The time stamp is written between the brackets or quotes: - Time-stamp: <1998-02-18 10:20:51 gildea> + Time-stamp: <2001-02-18 10:20:51 gildea> The time stamp is updated only if the variable `time-stamp-active' is non-nil. The format of the time stamp is set by the variable `time-stamp-format'. The variables `time-stamp-line-limit', `time-stamp-start', `time-stamp-end', @@ -251,7 +266,7 @@ template." search-limit) (if (stringp time-stamp-pattern) (progn - (string-match "\\`\\(\\(-?[0-9]+\\)/\\)?\\([^%]+\\)?\\(\\(.\\|\n\\)*%[-.,:@+_ #^()0-9]*[A-Za-z%]\\)?\\([^%]+\\)?\\'" time-stamp-pattern) + (string-match "\\`\\(\\(-?[0-9]+\\)/\\)?\\([^%]+\\)?\\(\\(%[-.,:@+_ #^()0-9]*[A-Za-z%][^%]*\\)*%[-.,:@+_ #^()0-9]*[A-Za-z%]\\)?\\([^%]+\\)?\\'" time-stamp-pattern) (and (match-beginning 2) (setq line-limit (string-to-int (match-string 2 time-stamp-pattern)))) @@ -275,9 +290,10 @@ template." ;; to output any warnings about time-stamp not being active. (setq ts-count 1))) ;; Figure out what lines the end should be on. - (let ((nl-start 0)) - (while (string-match "\n" ts-format nl-start) - (setq format-lines (1+ format-lines) nl-start (match-end 0)))) + (if (stringp ts-format) + (let ((nl-start 0)) + (while (string-match "\n" ts-format nl-start) + (setq format-lines (1+ format-lines) nl-start (match-end 0))))) (let ((nl-start 0)) (while (string-match "\n" ts-end nl-start) (setq end-lines (1+ end-lines) nl-start (match-end 0)))) @@ -307,7 +323,7 @@ template." (defun time-stamp-once (start search-limit ts-start ts-end ts-format format-lines end-lines) - "Update one time-stamp. Internal routine called by \\[time-stamp]. + "Update one time stamp. Internal routine called by \\[time-stamp]. Returns the end point, which is where `time-stamp' begins the next search." (let ((case-fold-search nil) (end nil) @@ -374,7 +390,7 @@ Returns the end point, which is where `time-stamp' begins the next search." ;;;###autoload (defun time-stamp-toggle-active (&optional arg) "Toggle `time-stamp-active', setting whether \\[time-stamp] updates a buffer. -With arg, turn time stamping on if and only if arg is positive." +With ARG, turn time stamping on if and only if arg is positive." (interactive "P") (setq time-stamp-active (if (null arg) @@ -385,7 +401,8 @@ With arg, turn time stamping on if and only if arg is positive." (defun time-stamp-string (&optional ts-format) "Generate the new string to be inserted by \\[time-stamp]. -Optionally use FORMAT." +Optionally use format TS-FORMAT instead of `time-stamp-format' to +format the string." (or ts-format (setq ts-format time-stamp-format)) (if (stringp ts-format) @@ -393,10 +410,10 @@ Optionally use FORMAT." (let ((ts-real-time-zone (getenv "TZ"))) (unwind-protect (progn - (setenv "TZ" time-stamp-time-zone) + (set-time-zone-rule time-stamp-time-zone) (format-time-string (time-stamp-string-preprocess ts-format))) - (setenv "TZ" ts-real-time-zone))) + (set-time-zone-rule ts-real-time-zone))) (format-time-string (time-stamp-string-preprocess ts-format))) ;; handle version 1 compatibility @@ -428,10 +445,10 @@ Optionally use FORMAT." ;;; The : modifier is a temporary conversion feature used to resolve ;;; ambiguous formats--formats that are changing (over time) incompatibly. (defun time-stamp-string-preprocess (format &optional time) - ;; Use a FORMAT to format date, time, file, and user information. - ;; Optional second argument TIME is only for testing. - ;; Implements non-time extensions to format-time-string - ;; and all time-stamp-format compatibility. + "Use a FORMAT to format date, time, file, and user information. +Optional second argument TIME is only for testing. +Implements non-time extensions to `format-time-string' +and all `time-stamp-format' compatibility." (let ((fmt-len (length format)) (ind 0) cur-char @@ -492,7 +509,7 @@ Optionally use FORMAT." "%%") ((eq cur-char ?a) ;day of week (if change-case - (format-time-string "%#A" time) + (format-time-string "%#a" time) (or alt-form (not (string-equal field-width "")) (time-stamp-conv-warn "%a" "%:a")) (if (and alt-form (not (string-equal field-width ""))) @@ -506,7 +523,7 @@ Optionally use FORMAT." (format-time-string "%#A" time))) ((eq cur-char ?b) ;month name (if change-case - (format-time-string "%#B" time) + (format-time-string "%#b" time) (or alt-form (not (string-equal field-width "")) (time-stamp-conv-warn "%b" "%:b")) (if (and alt-form (not (string-equal field-width ""))) @@ -572,33 +589,32 @@ Optionally use FORMAT." ((eq cur-char ?h) ;mail host name (time-stamp-mail-host-name)) )) - (if (string-equal field-width "") - (format "%s" field-result) - (let ((padded-result - (format (format "%%%s%c" - field-width - (if (numberp field-result) ?d ?s)) - (or field-result "")))) - (let ((initial-length (length padded-result)) - (desired-length (string-to-int field-width))) - (if (> initial-length desired-length) - ;; truncate strings on right, years on left - (if (stringp field-result) - (substring padded-result 0 desired-length) - (if (eq cur-char ?y) - (substring padded-result (- desired-length)) - padded-result)) ;non-year numbers don't truncate - padded-result))))) + (let ((padded-result + (format (format "%%%s%c" + field-width + (if (numberp field-result) ?d ?s)) + (or field-result "")))) + (let* ((initial-length (length padded-result)) + (desired-length (if (string-equal field-width "") + initial-length + (string-to-int field-width)))) + (if (> initial-length desired-length) + ;; truncate strings on right, years on left + (if (stringp field-result) + (substring padded-result 0 desired-length) + (if (eq cur-char ?y) + (substring padded-result (- desired-length)) + padded-result)) ;non-year numbers don't truncate + padded-result)))) (t (char-to-string cur-char))))) (setq ind (1+ ind))) result)) (defun time-stamp-do-number (format-char alt-form field-width time) - ;; Handle a compatible FORMAT-CHAR where only - ;; the default width/padding will change. - ;; ALT-FORM is whether `#' specified. FIELD-WIDTH is the string - ;; width specification or "". TIME is the time to convert. + "Handle compatible FORMAT-CHAR where only default width/padding will change. +ALT-FORM is whether `#' specified. FIELD-WIDTH is the string +width specification or \"\". TIME is the time to convert." (let ((format-string (concat "%" (char-to-string format-char)))) (and (not alt-form) (string-equal field-width "") (time-stamp-conv-warn format-string @@ -608,8 +624,8 @@ Optionally use FORMAT." (string-to-int (format-time-string format-string time))))) (defvar time-stamp-conversion-warn t - "Non-nil to warn about soon-to-be-unsupported forms in `time-stamp-format'. -In would be a bad idea to disable these warnings! + "Warn about soon-to-be-unsupported forms in `time-stamp-format'. +If nil, these warnings are disabled, which would be a bad idea! You really need to update your files instead. The new formats will work with old versions of Emacs. @@ -619,7 +635,8 @@ The new forms being recommended now will continue to work then.") (defun time-stamp-conv-warn (old-form new-form) - ;; Display a warning about a soon-to-be-obsolete format. + "Display a warning about a soon-to-be-obsolete format. +Suggests replacing OLD-FORM with NEW-FORM." (cond (time-stamp-conversion-warn (save-excursion @@ -669,8 +686,24 @@ around literals." ;;; Some functions used in time-stamp-format -;;; Could generate most of a message-id with -;;; '(time-stamp-yymmdd "" time-stamp-hhmm "@" time-stamp-mail-host-name) +;;; These functions have been obsolete since 1995 +;;; and will be removed in Emacs 22. +;;; Meanwhile, discourage other packages from using them. +(let ((obsolete-functions '(time-stamp-month-dd-yyyy + time-stamp-dd/mm/yyyy + time-stamp-mon-dd-yyyy + time-stamp-dd-mon-yy + time-stamp-yy/mm/dd + time-stamp-yyyy/mm/dd + time-stamp-yyyy-mm-dd + time-stamp-yymmdd + time-stamp-hh:mm:ss + time-stamp-hhmm))) + (while obsolete-functions + (make-obsolete (car obsolete-functions) + "use time-stamp-string or format-time-string instead." + "20.1") + (setq obsolete-functions (cdr obsolete-functions)))) ;;; pretty form, suitable for a title page