procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

time-stamp doc: recommend formats closer to format-time-string

Browse source 
* time-stamp.el (time-stamp-format, time-stamp-pattern): Update
recommended (documented) formats.  No code changes, just documentation.
All recommended formats are compatible at least as far back as Emacs
22.1 (released in 2007) and are now closer to compatibility with
format-time-string.

* time-stamp-tests.el: Update test comments to match.
This commit is contained in:
Stephen Gildea 2019-09-30 20:06:16 -07:00
parent 24a3288278
commit 8ba1ca54f3
3 changed files with 65 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
etc/NEWS
View file

@ -1995,6 +1995,27 @@ and 'gravatar-force-default'.
*** The built-in ada-mode is now deleted. The GNU ELPA package is a
good replacement, even in very large source files.
** Some conversions recommended for 'time-stamp-format' have changed.
The new documented/recommended %-conversions are closer to those
used by 'format-time-string' and are compatible at least as far back
as Emacs 22.1 (released in 2007).
Uppercase abbreviated day name of week: was %3A, now %#a
Full day name of week: was %:a, now %:A
Uppercase abbreviated month name: was %3B, now %#b
Full month name: was %:b, now %:B
Four-digit year: was %:y, now %Y
Lowercase timezone name: was %z, now %#Z
Fully-qualified host name: was %s, now %Q
Unqualified host name: (was none), now %q
Login name: was %u, now %l
User's full name: was %U, now %L
Merely having (add-hook 'before-save-hook 'time-stamp) in your
Emacs init file does not expose you to this change. However,
if you set 'time-stamp-format' or 'time-stamp-pattern' with a
file-local variable, you may need to update the value.
* New Modes and Packages in Emacs 27.1

43
lisp/time-stamp.el
View file

@ -41,7 +41,7 @@
:group 'data
:group 'extensions)
(defcustom time-stamp-format "%:y-%02m-%02d %02H:%02M:%02S %u"
(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
with %, as follows. The values of non-numeric formatted items depend
@ -49,26 +49,26 @@ 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'
%:b month name: `January'. %#B gives uppercase: `JANUARY'
%3b abbreviated month: `Jan'. %3B gives uppercase: `JAN'
%:A weekday name: `Monday' %#A gives uppercase: `MONDAY'
%3a abbreviated weekday: `Mon' %#a gives uppercase: `MON'
%:B month name: `January' %#B gives uppercase: `JANUARY'
%3b abbreviated month: `Jan' %#b gives uppercase: `JAN'
%02d day of month
%02H 24-hour clock hour
%02I 12-hour clock hour
%02m month number
%02M minute
%#p `am' or `pm'. %P gives uppercase: `AM' or `PM'
%#p `am' or `pm' %P gives uppercase: `AM' or `PM'
%02S seconds
%w day number of week, Sunday is 0
%02y 2-digit year: `03' %:y 4-digit year: `2003'
%z time zone name: `est'. %Z gives uppercase: `EST'
%02y 2-digit year: `03' %Y 4-digit year: `2003'
%#Z lowercase time zone name: `est' %Z gives uppercase: `EST'
Non-date items:
%% a literal percent character: `%'
%f file name without directory %F gives absolute pathname
%s system name
%u user's login name %U user's full name
%l login name %L full name of logged-in user
%q unqualified host name %Q fully-qualified host name
%h mail host name
Decimal digits between the % and the type character specify the
@ -76,16 +76,15 @@ field width. Strings are truncated on the right; years on the left.
A leading zero in the field width zero-fills a number.
For example, to get the format used by the `date' command,
use \"%3a %3b %2d %02H:%02M:%02S %Z %:y\".
use \"%3a %3b %2d %02H:%02M:%02S %Z %Y\".
In the future these formats will be aligned more with `format-time-string'.
Because of this transition, the default padding for numeric formats will
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."
The default padding of some formats has changed to be more compatible
with format-time-string. To be compatible with older versions of Emacs,
specify a padding width (as shown) or use the : modifier to request the
transitional behavior (again, as shown)."
:type 'string
:group 'time-stamp
:version "20.1")
:version "27.1")
;;;###autoload(put 'time-stamp-format 'safe-local-variable 'stringp)
(defcustom time-stamp-active t
@ -227,13 +226,13 @@ Examples:
\"-10/\" (sets only `time-stamp-line-limit')
\"-9/^Last modified: %%$\" (sets `time-stamp-line-limit',
`time-stamp-start', `time-stamp-end' and `time-stamp-format')
`time-stamp-start' and `time-stamp-end')
\"@set Time-stamp: %:b %:d, %:y$\" (sets `time-stamp-start',
`time-stamp-end' and `time-stamp-format')
\"@set Time-stamp: %:B %1d, %Y$\" (sets `time-stamp-start',
`time-stamp-format' and `time-stamp-end')
\"newcommand{\\\\\\\\timestamp}{%%}\" (sets `time-stamp-start',
`time-stamp-end' and `time-stamp-format')
\"newcommand{\\\\\\\\timestamp}{%%}\" (sets `time-stamp-start'
and `time-stamp-end')
Do not change `time-stamp-pattern' `time-stamp-line-limit',
`time-stamp-start', or `time-stamp-end' for yourself or you will be

42
test/lisp/time-stamp-tests.el
View file

@ -63,9 +63,10 @@
;; implemented and documented since 1997
(should (equal (time-stamp-string "%3a" ref-time) "Mon"))
(should (equal (time-stamp-string "%#A" ref-time) "MONDAY"))
;; documented 1997-2019
(should (equal (time-stamp-string "%3A" ref-time) "MON"))
(should (equal (time-stamp-string "%:a" ref-time) "Monday"))
;; implemented since 2001, undocumented future formats
;; implemented since 2001, documented since 2019
(should (equal (time-stamp-string "%#a" ref-time) "MON"))
(should (equal (time-stamp-string "%:A" ref-time) "Monday"))
;; warned since 1997, will change
@ -82,9 +83,10 @@
;; implemented and documented since 1997
(should (equal (time-stamp-string "%3b" ref-time) "Jan"))
(should (equal (time-stamp-string "%#B" ref-time) "JANUARY"))
;; documented 1997-2019
(should (equal (time-stamp-string "%3B" ref-time) "JAN"))
(should (equal (time-stamp-string "%:b" ref-time) "January"))
;; implemented since 2001, undocumented future formats
;; implemented since 2001, documented since 2019
(should (equal (time-stamp-string "%#b" ref-time) "JAN"))
(should (equal (time-stamp-string "%:B" ref-time) "January"))
;; warned since 1997, will change
@ -103,10 +105,10 @@
(should (equal (time-stamp-string "%2d" ref-time2) "18"))
(should (equal (time-stamp-string "%02d" ref-time) "02"))
(should (equal (time-stamp-string "%02d" ref-time2) "18"))
;; implemented and documented since 1997
;; documented 1997-2019
(should (equal (time-stamp-string "%:d" ref-time) "2"))
(should (equal (time-stamp-string "%:d" ref-time2) "18"))
;; implemented since 1997, undocumented future format
;; implemented since 1997, documented since 2019
(should (equal (time-stamp-string "%1d" ref-time) "2"))
(should (equal (time-stamp-string "%1d" ref-time2) "18"))
;; warned since 1997, will change
@ -125,11 +127,11 @@
(should (equal (time-stamp-string "%02H" ref-time) "15"))
(should (equal (time-stamp-string "%02H" ref-time2) "12"))
(should (equal (time-stamp-string "%02H" ref-time3) "06"))
;; implemented and documented since 1997
;; documented 1997-2019
(should (equal (time-stamp-string "%:H" ref-time) "15"))
(should (equal (time-stamp-string "%:H" ref-time2) "12"))
(should (equal (time-stamp-string "%:H" ref-time3) "6"))
;; implemented since 1997, undocumented future format
;; implemented since 1997, documented since 2019
(should (equal (time-stamp-string "%1H" ref-time) "15"))
(should (equal (time-stamp-string "%1H" ref-time2) "12"))
(should (equal (time-stamp-string "%1H" ref-time3) "6"))
@ -151,11 +153,11 @@
(should (equal (time-stamp-string "%02I" ref-time) "03"))
(should (equal (time-stamp-string "%02I" ref-time2) "12"))
(should (equal (time-stamp-string "%02I" ref-time3) "06"))
;; implemented and documented since 1997
;; documented 1997-2019
(should (equal (time-stamp-string "%:I" ref-time) "3")) ;PM
(should (equal (time-stamp-string "%:I" ref-time2) "12")) ;PM
(should (equal (time-stamp-string "%:I" ref-time3) "6")) ;AM
;; implemented since 1997, undocumented future format
;; implemented since 1997, documented since 2019
(should (equal (time-stamp-string "%1I" ref-time) "3"))
(should (equal (time-stamp-string "%1I" ref-time2) "12"))
(should (equal (time-stamp-string "%1I" ref-time3) "6"))
@ -175,10 +177,10 @@
(should (equal (time-stamp-string "%2m" ref-time2) "11"))
(should (equal (time-stamp-string "%02m" ref-time) "01"))
(should (equal (time-stamp-string "%02m" ref-time2) "11"))
;; implemented and documented since 1997
;; documented 1997-2019
(should (equal (time-stamp-string "%:m" ref-time) "1"))
(should (equal (time-stamp-string "%:m" ref-time2) "11"))
;; implemented since 1997, undocumented future format
;; implemented since 1997, documented since 2019
(should (equal (time-stamp-string "%1m" ref-time) "1"))
(should (equal (time-stamp-string "%1m" ref-time2) "11"))
;; warned since 1997, will change
@ -195,10 +197,10 @@
(should (equal (time-stamp-string "%2M" ref-time2) "14"))
(should (equal (time-stamp-string "%02M" ref-time) "04"))
(should (equal (time-stamp-string "%02M" ref-time2) "14"))
;; implemented and documented since 1997
;; documented 1997-2019
(should (equal (time-stamp-string "%:M" ref-time) "4"))
(should (equal (time-stamp-string "%:M" ref-time2) "14"))
;; implemented since 1997, undocumented future format
;; implemented since 1997, documented since 2019
(should (equal (time-stamp-string "%1M" ref-time) "4"))
(should (equal (time-stamp-string "%1M" ref-time2) "14"))
;; warned since 1997, will change
@ -215,10 +217,10 @@
(should (equal (time-stamp-string "%2S" ref-time2) "15"))
(should (equal (time-stamp-string "%02S" ref-time) "05"))
(should (equal (time-stamp-string "%02S" ref-time2) "15"))
;; implemented and documented since 1997
;; documented 1997-2019
(should (equal (time-stamp-string "%:S" ref-time) "5"))
(should (equal (time-stamp-string "%:S" ref-time2) "15"))
;; implemented since 1997, undocumented future format
;; implemented since 1997, documented since 2019
(should (equal (time-stamp-string "%1S" ref-time) "5"))
(should (equal (time-stamp-string "%1S" ref-time2) "15"))
;; warned since 1997, will change
@ -251,9 +253,9 @@
(with-time-stamp-test-env
;; implemented and documented since 1995
(should (equal (time-stamp-string "%02y" ref-time) "06"))
;; implemented and documented since 1997
;; documented 1997-2019
(should (equal (time-stamp-string "%:y" ref-time) "2006"))
;; implemented since 1997, undocumented future format
;; implemented since 1997, documented since 2019
(should (equal (time-stamp-string "%Y" ref-time) "2006"))
;; warned since 1997, will change
(time-stamp-should-warn (equal (time-stamp-string "%y" ref-time) "2006"))))
@ -263,8 +265,9 @@
(with-time-stamp-test-env
;; implemented and documented since 1995
(should (equal (time-stamp-string "%Z" ref-time) "GMT"))
;; documented 1995-2019
(should (equal (time-stamp-string "%z" ref-time) "gmt"))
;; implemented since 1997, undocumented future format
;; implemented since 1997, documented since 2019
(should (equal (time-stamp-string "%#Z" ref-time) "gmt"))))
(ert-deftest time-stamp-test-non-date-conversions ()
@ -277,14 +280,15 @@
(should (equal
(time-stamp-string "%F" ref-time) "/emacs/test/time-stamped-file"))
(should (equal (time-stamp-string "%h" ref-time) "test-mail-host-name"))
;; documented 1995-2019
(should (equal
(time-stamp-string "%s" ref-time) "test-system-name.example.org"))
(should (equal (time-stamp-string "%U" ref-time) "Time Stamp Tester"))
(should (equal (time-stamp-string "%u" ref-time) "test-logname"))
;; implemented since 2001, undocumented future formats
;; implemented since 2001, documented since 2019
(should (equal (time-stamp-string "%L" ref-time) "Time Stamp Tester"))
(should (equal (time-stamp-string "%l" ref-time) "test-logname"))
;; implemented since 2007, undocumented future formats
;; implemented since 2007, documented since 2019
(should (equal
(time-stamp-string "%Q" ref-time) "test-system-name.example.org"))
(should (equal