From: Stephen Gildea Date: Sun, 26 Sep 2021 15:23:29 +0000 (-0700) Subject: ; Clarify and simplify time-stamp comments X-Git-Tag: emacs-28.0.90~596 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=4cc43449432427817400bad12e7ef722e6591a21;p=emacs.git ; Clarify and simplify time-stamp comments * lisp/time-stamp.el (time-stamp-end, time-stamp-string-preprocess, time-stamp-formatz-from-parsed-options): Simplify doc. * test/lisp/time-stamp-tests.el (time-stamp-custom-pattern): Refactor to set limit-number only once. --- diff --git a/lisp/time-stamp.el b/lisp/time-stamp.el index 5258742845e..663773281b5 100644 --- a/lisp/time-stamp.el +++ b/lisp/time-stamp.el @@ -41,6 +41,7 @@ :group 'data :group 'extensions) + (defcustom time-stamp-format "%Y-%02m-%02d %02H:%02M:%02S %l" "Format of the string inserted by \\[time-stamp]. This is a string, used verbatim except for character sequences beginning @@ -92,6 +93,7 @@ edited by older versions of Emacs also, do not use this format yet." :version "27.1") ;;;###autoload(put 'time-stamp-format 'safe-local-variable 'stringp) + (defcustom time-stamp-active t "Non-nil to enable time-stamping of buffers by \\[time-stamp]. Can be toggled by \\[time-stamp-toggle-active]. @@ -109,6 +111,7 @@ line to a local variables list near the end of the file: See also the variable `time-stamp-warn-inactive'." :type 'boolean) + (defcustom time-stamp-warn-inactive t "Have \\[time-stamp] warn if a buffer did not get time-stamped. If non-nil, a warning is displayed if `time-stamp-active' has @@ -117,6 +120,7 @@ otherwise would have been updated." :type 'boolean :version "19.29") + (defcustom time-stamp-time-zone nil "The time zone to be used by \\[time-stamp]. Its format is that of the ZONE argument of the `format-time-string' function." @@ -131,6 +135,7 @@ Its format is that of the ZONE argument of the `format-time-string' function." :version "20.1") ;;;###autoload(put 'time-stamp-time-zone 'safe-local-variable 'time-stamp-zone-type-p) + ;;;###autoload (defun time-stamp-zone-type-p (zone) "Return whether or not ZONE is of the correct type for a timezone rule. @@ -143,6 +148,7 @@ Valid ZONE values are described in the documentation of `format-time-string'." (stringp (cadr zone))) (integerp zone))) + ;;; Do not change time-stamp-line-limit, time-stamp-start, ;;; time-stamp-end, time-stamp-pattern, time-stamp-inserts-lines, ;;; or time-stamp-count in your .emacs or you will be incompatible @@ -167,6 +173,7 @@ If you were to change `time-stamp-line-limit', `time-stamp-start', would be incompatible with other people's files.") ;;;###autoload(put 'time-stamp-line-limit 'safe-local-variable 'integerp) + (defvar time-stamp-start "Time-stamp:[ \t]+\\\\?[\"<]+" ;Do not change! "Regexp after which the time stamp is written by \\[time-stamp]. @@ -180,6 +187,7 @@ If you were to change `time-stamp-line-limit', `time-stamp-start', would be incompatible with other people's files.") ;;;###autoload(put 'time-stamp-start 'safe-local-variable 'stringp) + (defvar time-stamp-end "\\\\?[\">]" ;Do not change! "Regexp marking the text after the time stamp. \\[time-stamp] deletes the text between the first match of `time-stamp-start' @@ -192,8 +200,8 @@ or `time-stamp-format'. The end text normally starts on the same line as the start text ends, but if there are any newlines in `time-stamp-format', the same number -of newlines must separate the start and end. \\[time-stamp] tries -to not change the number of lines in the buffer. `time-stamp-inserts-lines' +of newlines must separate the start and end. Thus \\[time-stamp] tries +to not change the number of lines in the buffer; `time-stamp-inserts-lines' controls this behavior. These variables are best changed with file-local variables. @@ -469,9 +477,8 @@ normally the current time is used." (defconst time-stamp-no-file "(no file)" "String to use when the buffer is not associated with a file.") -;;; time-stamp is transitioning to be compatible with format-time-string. -;;; During the process, this function implements -;;; intermediate, compatible formats. +;;; time-stamp is transitioning to be more compatible with format-time-string. +;;; This function implements the differences. ;;; At all times, all the formats recommended in the doc string ;;; of time-stamp-format will work not only in the current version of ;;; Emacs, but in all versions that have been released within the past @@ -713,6 +720,7 @@ This is an internal helper for `time-stamp-string-preprocess'." "" ;discourage "%:2d" and the like (string-to-number (time-stamp--format format-string time))))) + (defvar time-stamp-conversion-warn t "Enable warnings about soon-to-be-unsupported forms in `time-stamp-format'. If nil, these warnings are disabled, which would be a bad idea! @@ -740,6 +748,7 @@ Suggests replacing OLD-FORM with NEW-FORM." (insert "\"" old-form "\" -- use " new-form "\n")) (display-buffer "*Time-stamp-compatibility*")))) + ;;; A principled, expressive implementation of time zone offset ;;; formatting ("%z" and variants). @@ -816,15 +825,13 @@ Suggests replacing OLD-FORM with NEW-FORM." ;;; * ABNF syntax of the offset string produced by %z -;; offset = sign hours [minutes [seconds]] padding / -;; sign hours [colonminutes [colonseconds]] padding / -;; sign bighours colonminutes [colonseconds] padding +;; offset = sign ( hours [minutes [seconds]] / +;; hours [":" minutes [":" seconds]] / +;; bighours ":" minutes [":" seconds] ) padding ;; sign = "+" / "-" ;; hours = digitpair ;; minutes = digitpair ;; seconds = digitpair -;; colonminutes = ":" minutes -;; colonseconds = ":" seconds ;; digitpair = digit digit ;; digit = "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" ;; bighours = 1*digit digitpair @@ -837,8 +844,6 @@ Suggests replacing OLD-FORM with NEW-FORM." field-width offset-secs) "Formats a time offset according to a %z variation. -The caller of this function must have already parsed the %z format -string; this function accepts just the parts of the format. With no flags, the output includes hours and minutes: +-HHMM unless there is a non-zero seconds part, in which case the seconds @@ -865,7 +870,14 @@ added on the right if necessary. The added characters will be spaces unless FLAG-PAD-ZEROS-FIRST is non-nil. OFFSET-SECS is the time zone offset (in seconds east of UTC) to be -formatted according to the preceding parameters." +formatted according to the preceding parameters. + +This is an internal function used by `time-stamp'." + ;; The caller of this function must have already parsed the %z + ;; format string; this function accepts just the parts of the format. + ;; `time-stamp-string-preprocess' is the full-fledged parser normally + ;; used. The unit test (in time-stamp-tests.el) defines the simpler + ;; parser `format-time-offset'. (let ((hrs (/ (abs offset-secs) 3600)) (mins (/ (% (abs offset-secs) 3600) 60)) (secs (% (abs offset-secs) 60)) diff --git a/test/lisp/time-stamp-tests.el b/test/lisp/time-stamp-tests.el index 4e6fbbba923..dc628af19fd 100644 --- a/test/lisp/time-stamp-tests.el +++ b/test/lisp/time-stamp-tests.el @@ -141,9 +141,9 @@ ts-format _format-lines _end-lines) ;; Verify that time-stamp parsed time-stamp-pattern and ;; called us with the correct pieces. - (let ((limit-number (string-to-number line-limit1))) - (if (equal line-limit1 "") - (setq limit-number time-stamp-line-limit)) + (let ((limit-number (if (equal line-limit1 "") + time-stamp-line-limit + (string-to-number line-limit1)))) (goto-char (point-min)) (if (> limit-number 0) (should (= search-limit (line-beginning-position