Mercurial > hg > octave-kai > gnulib-hg
changeset 13750:c67c281ae7ff
More renaming from 'getdate' to 'get_date'.
* doc/get_date.texi: Renamed from doc/getdate.texi.
* modules/get_date (Files): Update.
* MODULES.html.sh (Date and time <time.h>): Update.
* DEPENDENCIES: Update.
* gnulib-tool: Update comment.
* m4/bison.m4 (gl_BISON): Likewise.
* m4/get_date.m4 (gl_GET_DATE): Likewise.
author | Bruno Haible <bruno@clisp.org> |
---|---|
date | Thu, 30 Sep 2010 23:29:13 +0200 |
parents | 259247e24a97 |
children | 0bf7f277a1af |
files | ChangeLog DEPENDENCIES MODULES.html.sh NEWS doc/get_date.texi doc/getdate.texi gnulib-tool m4/bison.m4 m4/get_date.m4 modules/get_date |
diffstat | 10 files changed, 577 insertions(+), 565 deletions(-) [+] |
line wrap: on
line diff
--- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2010-09-30 Bruno Haible <bruno@clisp.org> + + More renaming from 'getdate' to 'get_date'. + * doc/get_date.texi: Renamed from doc/getdate.texi. + * modules/get_date (Files): Update. + * MODULES.html.sh (Date and time <time.h>): Update. + * DEPENDENCIES: Update. + * gnulib-tool: Update comment. + * m4/bison.m4 (gl_BISON): Likewise. + * m4/get_date.m4 (gl_GET_DATE): Likewise. + 2010-09-30 Justin Clift <jclift@redhat.com> (tiny change) bootstrap: support ACLOCAL_FLAGS during aclocal
--- a/DEPENDENCIES +++ b/DEPENDENCIES @@ -101,7 +101,7 @@ * Bison 2.0 or newer. + Recommended. - Needed if you use the 'getdate' module. + Needed if you use the 'get_date' module. + Homepage: http://www.gnu.org/software/bison/ + Download:
--- a/MODULES.html.sh +++ b/MODULES.html.sh @@ -1835,7 +1835,7 @@ func_echo "$element" func_begin_table - func_module getdate + func_module get_date func_module timegm func_module tzset func_end_table
--- a/NEWS +++ b/NEWS @@ -14,7 +14,8 @@ 2010-09-30 getdate This module is deprecated. Please use get_date for get_date(), or help us write getdate-posix - for getdate(). + for getdate(). Also, doc/getdate.texi has been + renamed to doc/get_date.texi. 2010-09-29 sys_wait This module no longer provides the waitpid() function. If you need this function, you now need
new file mode 100644 --- /dev/null +++ b/doc/get_date.texi @@ -0,0 +1,556 @@ +@c GNU date syntax documentation + +@c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, +@c 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.3 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +@node Date input formats +@chapter Date input formats + +@cindex date input formats +@findex get_date + +First, a quote: + +@quotation +Our units of temporal measurement, from seconds on up to months, are so +complicated, asymmetrical and disjunctive so as to make coherent mental +reckoning in time all but impossible. Indeed, had some tyrannical god +contrived to enslave our minds to time, to make it all but impossible +for us to escape subjection to sodden routines and unpleasant surprises, +he could hardly have done better than handing down our present system. +It is like a set of trapezoidal building blocks, with no vertical or +horizontal surfaces, like a language in which the simplest thought +demands ornate constructions, useless particles and lengthy +circumlocutions. Unlike the more successful patterns of language and +science, which enable us to face experience boldly or at least +level-headedly, our system of temporal calculation silently and +persistently encourages our terror of time. + +@dots{} It is as though architects had to measure length in feet, width +in meters and height in ells; as though basic instruction manuals +demanded a knowledge of five different languages. It is no wonder then +that we often look into our own immediate past or future, last Tuesday +or a week from Sunday, with feelings of helpless confusion. @dots{} + +--- Robert Grudin, @cite{Time and the Art of Living}. +@end quotation + +This section describes the textual date representations that @sc{gnu} +programs accept. These are the strings you, as a user, can supply as +arguments to the various programs. The C interface (via the +@code{get_date} function) is not described here. + +@menu +* General date syntax:: Common rules. +* Calendar date items:: 19 Dec 1994. +* Time of day items:: 9:20pm. +* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}. +* Day of week items:: Monday and others. +* Relative items in date strings:: next tuesday, 2 years ago. +* Pure numbers in date strings:: 19931219, 1440. +* Seconds since the Epoch:: @@1078100502. +* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". +* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al. +@end menu + + +@node General date syntax +@section General date syntax + +@cindex general date syntax + +@cindex items in date strings +A @dfn{date} is a string, possibly empty, containing many items +separated by whitespace. The whitespace may be omitted when no +ambiguity arises. The empty string means the beginning of today (i.e., +midnight). Order of the items is immaterial. A date string may contain +many flavors of items: + +@itemize @bullet +@item calendar date items +@item time of day items +@item time zone items +@item day of the week items +@item relative items +@item pure numbers. +@end itemize + +@noindent We describe each of these item types in turn, below. + +@cindex numbers, written-out +@cindex ordinal numbers +@findex first @r{in date strings} +@findex next @r{in date strings} +@findex last @r{in date strings} +A few ordinal numbers may be written out in words in some contexts. This is +most useful for specifying day of the week items or relative items (see +below). Among the most commonly used ordinal numbers, the word +@samp{last} stands for @math{-1}, @samp{this} stands for 0, and +@samp{first} and @samp{next} both stand for 1. Because the word +@samp{second} stands for the unit of time there is no way to write the +ordinal number 2, but for convenience @samp{third} stands for 3, +@samp{fourth} for 4, @samp{fifth} for 5, +@samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8, +@samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and +@samp{twelfth} for 12. + +@cindex months, written-out +When a month is written this way, it is still considered to be written +numerically, instead of being ``spelled in full''; this changes the +allowed strings. + +@cindex language, in dates +In the current implementation, only English is supported for words and +abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first}, +@samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}. + +@cindex language, in dates +@cindex time zone item +The output of the @command{date} command +is not always acceptable as a date string, +not only because of the language problem, but also because there is no +standard meaning for time zone items like @samp{IST}. When using +@command{date} to generate a date string intended to be parsed later, +specify a date format that is independent of language and that does not +use time zone items other than @samp{UTC} and @samp{Z}. Here are some +ways to do this: + +@example +$ LC_ALL=C TZ=UTC0 date +Mon Mar 1 00:21:42 UTC 2004 +$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' +2004-03-01 00:21:42Z +$ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. +2004-02-29 16:21:42,692722128-0800 +$ date --rfc-2822 # a GNU extension +Sun, 29 Feb 2004 16:21:42 -0800 +$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. +2004-02-29 16:21:42 -0800 +$ date +'@@%s.%N' # %s and %N are GNU extensions. +@@1078100502.692722128 +@end example + +@cindex case, ignored in dates +@cindex comments, in dates +Alphabetic case is completely ignored in dates. Comments may be introduced +between round parentheses, as long as included parentheses are properly +nested. Hyphens not followed by a digit are currently ignored. Leading +zeros on numbers are ignored. + +Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are +rejected. In the typical case of a host that does not support leap +seconds, a time like @samp{23:59:60} is rejected even if it +corresponds to a valid leap second. + + +@node Calendar date items +@section Calendar date items + +@cindex calendar date item + +A @dfn{calendar date item} specifies a day of the year. It is +specified differently, depending on whether the month is specified +numerically or literally. All these strings specify the same calendar date: + +@example +1972-09-24 # @sc{iso} 8601. +72-9-24 # Assume 19xx for 69 through 99, + # 20xx for 00 through 68. +72-09-24 # Leading zeros are ignored. +9/24/72 # Common U.S. writing. +24 September 1972 +24 Sept 72 # September has a special abbreviation. +24 Sep 72 # Three-letter abbreviations always allowed. +Sep 24, 1972 +24-sep-72 +24sep72 +@end example + +The year can also be omitted. In this case, the last specified year is +used, or the current year if none. For example: + +@example +9/24 +sep 24 +@end example + +Here are the rules. + +@cindex @sc{iso} 8601 date format +@cindex date format, @sc{iso} 8601 +For numeric months, the @sc{iso} 8601 format +@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is +any positive number, @var{month} is a number between 01 and 12, and +@var{day} is a number between 01 and 31. A leading zero must be present +if a number is less than ten. If @var{year} is 68 or smaller, then 2000 +is added to it; otherwise, if @var{year} is less than 100, +then 1900 is added to it. The construct +@samp{@var{month}/@var{day}/@var{year}}, popular in the United States, +is accepted. Also @samp{@var{month}/@var{day}}, omitting the year. + +@cindex month names in date strings +@cindex abbreviations for months +Literal months may be spelled out in full: @samp{January}, +@samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June}, +@samp{July}, @samp{August}, @samp{September}, @samp{October}, +@samp{November} or @samp{December}. Literal months may be abbreviated +to their first three letters, possibly followed by an abbreviating dot. +It is also permitted to write @samp{Sept} instead of @samp{September}. + +When months are written literally, the calendar date may be given as any +of the following: + +@example +@var{day} @var{month} @var{year} +@var{day} @var{month} +@var{month} @var{day} @var{year} +@var{day}-@var{month}-@var{year} +@end example + +Or, omitting the year: + +@example +@var{month} @var{day} +@end example + + +@node Time of day items +@section Time of day items + +@cindex time of day item + +A @dfn{time of day item} in date strings specifies the time on a given +day. Here are some examples, all of which represent the same time: + +@example +20:02:00.000000 +20:02 +8:02pm +20:02-0500 # In @sc{est} (U.S. Eastern Standard Time). +@end example + +More generally, the time of day may be given as +@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is +a number between 0 and 23, @var{minute} is a number between 0 and +59, and @var{second} is a number between 0 and 59 possibly followed by +@samp{.} or @samp{,} and a fraction containing one or more digits. +Alternatively, +@samp{:@var{second}} can be omitted, in which case it is taken to +be zero. On the rare hosts that support leap seconds, @var{second} +may be 60. + +@findex am @r{in date strings} +@findex pm @r{in date strings} +@findex midnight @r{in date strings} +@findex noon @r{in date strings} +If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.} +or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and +@samp{:@var{minute}} may be omitted (taken to be zero). @samp{am} +indicates the first half of the day, @samp{pm} indicates the second +half of the day. In this notation, 12 is the predecessor of 1: +midnight is @samp{12am} while noon is @samp{12pm}. +(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm}, +as opposed to the old tradition derived from Latin +which uses @samp{12m} for noon and @samp{12pm} for midnight.) + +@cindex time zone correction +@cindex minutes, time zone correction by +The time may alternatively be followed by a time zone correction, +expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+} +or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number +of zone minutes. +The zone minutes term, @var{mm}, may be omitted, in which case +the one- or two-digit correction is interpreted as a number of hours. +You can also separate @var{hh} from @var{mm} with a colon. +When a time zone correction is given this way, it +forces interpretation of the time relative to +Coordinated Universal Time (@sc{utc}), overriding any previous +specification for the time zone or the local time zone. For example, +@samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours +ahead of @sc{utc} (e.g., India). +This is the best way to +specify a time zone correction by fractional parts of an hour. +The maximum zone correction is 24 hours. + +Either @samp{am}/@samp{pm} or a time zone correction may be specified, +but not both. + + +@node Time zone items +@section Time zone items + +@cindex time zone item + +A @dfn{time zone item} specifies an international time zone, indicated +by a small set of letters, e.g., @samp{UTC} or @samp{Z} +for Coordinated Universal +Time. Any included periods are ignored. By following a +non-daylight-saving time zone by the string @samp{DST} in a separate +word (that is, separated by some white space), the corresponding +daylight saving time zone may be specified. +Alternatively, a non-daylight-saving time zone can be followed by a +time zone correction, to add the two values. This is normally done +only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to +@samp{+05:30}. + +Time zone items other than @samp{UTC} and @samp{Z} +are obsolescent and are not recommended, because they +are ambiguous; for example, @samp{EST} has a different meaning in +Australia than in the United States. Instead, it's better to use +unambiguous numeric time zone corrections like @samp{-0500}, as +described in the previous section. + +If neither a time zone item nor a time zone correction is supplied, +time stamps are interpreted using the rules of the default time zone +(@pxref{Specifying time zone rules}). + + +@node Day of week items +@section Day of week items + +@cindex day of week item + +The explicit mention of a day of the week will forward the date +(only if necessary) to reach that day of the week in the future. + +Days of the week may be spelled out in full: @samp{Sunday}, +@samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday}, +@samp{Friday} or @samp{Saturday}. Days may be abbreviated to their +first three letters, optionally followed by a period. The special +abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for +@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are +also allowed. + +@findex next @var{day} +@findex last @var{day} +A number may precede a day of the week item to move forward +supplementary weeks. It is best used in expression like @samp{third +monday}. In this context, @samp{last @var{day}} or @samp{next +@var{day}} is also acceptable; they move one week before or after +the day that @var{day} by itself would represent. + +A comma following a day of the week item is ignored. + + +@node Relative items in date strings +@section Relative items in date strings + +@cindex relative items in date strings +@cindex displacement of dates + +@dfn{Relative items} adjust a date (or the current date if none) forward +or backward. The effects of relative items accumulate. Here are some +examples: + +@example +1 year +1 year ago +3 years +2 days +@end example + +@findex year @r{in date strings} +@findex month @r{in date strings} +@findex fortnight @r{in date strings} +@findex week @r{in date strings} +@findex day @r{in date strings} +@findex hour @r{in date strings} +@findex minute @r{in date strings} +The unit of time displacement may be selected by the string @samp{year} +or @samp{month} for moving by whole years or months. These are fuzzy +units, as years and months are not all of equal duration. More precise +units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7 +days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes, +@samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or +@samp{sec} worth one second. An @samp{s} suffix on these units is +accepted and ignored. + +@findex ago @r{in date strings} +The unit of time may be preceded by a multiplier, given as an optionally +signed number. Unsigned numbers are taken as positively signed. No +number at all implies 1 for a multiplier. Following a relative item by +the string @samp{ago} is equivalent to preceding the unit by a +multiplier with value @math{-1}. + +@findex day @r{in date strings} +@findex tomorrow @r{in date strings} +@findex yesterday @r{in date strings} +The string @samp{tomorrow} is worth one day in the future (equivalent +to @samp{day}), the string @samp{yesterday} is worth +one day in the past (equivalent to @samp{day ago}). + +@findex now @r{in date strings} +@findex today @r{in date strings} +@findex this @r{in date strings} +The strings @samp{now} or @samp{today} are relative items corresponding +to zero-valued time displacement, these strings come from the fact +a zero-valued time displacement represents the current time when not +otherwise changed by previous items. They may be used to stress other +items, like in @samp{12:00 today}. The string @samp{this} also has +the meaning of a zero-valued time displacement, but is preferred in +date strings like @samp{this thursday}. + +When a relative item causes the resulting date to cross a boundary +where the clocks were adjusted, typically for daylight saving time, +the resulting date and time are adjusted accordingly. + +The fuzz in units can cause problems with relative items. For +example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01, +because 2003-06-31 is an invalid date. To determine the previous +month more reliably, you can ask for the month before the 15th of the +current month. For example: + +@example +$ date -R +Thu, 31 Jul 2003 13:02:39 -0700 +$ date --date='-1 month' +'Last month was %B?' +Last month was July? +$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' +Last month was June! +@end example + +Also, take care when manipulating dates around clock changes such as +daylight saving leaps. In a few cases these have added or subtracted +as much as 24 hours from the clock, so it is often wise to adopt +universal time by setting the @env{TZ} environment variable to +@samp{UTC0} before embarking on calendrical calculations. + +@node Pure numbers in date strings +@section Pure numbers in date strings + +@cindex pure numbers in date strings + +The precise interpretation of a pure decimal number depends +on the context in the date string. + +If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no +other calendar date item (@pxref{Calendar date items}) appears before it +in the date string, then @var{yyyy} is read as the year, @var{mm} as the +month number and @var{dd} as the day of the month, for the specified +calendar date. + +If the decimal number is of the form @var{hh}@var{mm} and no other time +of day item appears before it in the date string, then @var{hh} is read +as the hour of the day and @var{mm} as the minute of the hour, for the +specified time of day. @var{mm} can also be omitted. + +If both a calendar date and a time of day appear to the left of a number +in the date string, but no relative item, then the number overrides the +year. + + +@node Seconds since the Epoch +@section Seconds since the Epoch + +If you precede a number with @samp{@@}, it represents an internal time +stamp as a count of seconds. The number can contain an internal +decimal point (either @samp{.} or @samp{,}); any excess precision not +supported by the internal representation is truncated toward minus +infinity. Such a number cannot be combined with any other date +item, as it specifies a complete time stamp. + +@cindex beginning of time, for @acronym{POSIX} +@cindex epoch, for @acronym{POSIX} +Internally, computer times are represented as a count of seconds since +an epoch---a well-defined point of time. On @acronym{GNU} and +@acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so +@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01 +00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other +@acronym{POSIX}-compliant systems support such times as an extension +to @acronym{POSIX}, using negative counts, so that @samp{@@-1} +represents 1969-12-31 23:59:59 @sc{utc}. + +Traditional Unix systems count seconds with 32-bit two's-complement +integers and can represent times from 1901-12-13 20:45:52 through +2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts +of seconds with nanosecond subcounts, and can represent all the times +in the known lifetime of the universe to a resolution of 1 nanosecond. + +On most hosts, these counts ignore the presence of leap seconds. +For example, on most hosts @samp{@@915148799} represents 1998-12-31 +23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00 +@sc{utc}, and there is no way to represent the intervening leap second +1998-12-31 23:59:60 @sc{utc}. + +@node Specifying time zone rules +@section Specifying time zone rules + +@vindex TZ +Normally, dates are interpreted using the rules of the current time +zone, which in turn are specified by the @env{TZ} environment +variable, or by a system default if @env{TZ} is not set. To specify a +different set of default time zone rules that apply just to one date, +start the date with a string of the form @samp{TZ="@var{rule}"}. The +two quote characters (@samp{"}) must be present in the date, and any +quotes or backslashes within @var{rule} must be escaped by a +backslash. + +For example, with the @acronym{GNU} @command{date} command you can +answer the question ``What time is it in New York when a Paris clock +shows 6:30am on October 31, 2004?'' by using a date beginning with +@samp{TZ="Europe/Paris"} as shown in the following shell transcript: + +@example +$ export TZ="America/New_York" +$ date --date='TZ="Europe/Paris" 2004-10-31 06:30' +Sun Oct 31 01:30:00 EDT 2004 +@end example + +In this example, the @option{--date} operand begins with its own +@env{TZ} setting, so the rest of that operand is processed according +to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31 +06:30} as if it were in Paris. However, since the output of the +@command{date} command is processed according to the overall time zone +rules, it uses New York time. (Paris was normally six hours ahead of +New York in 2004, but this example refers to a brief Halloween period +when the gap was five hours.) + +A @env{TZ} value is a rule that typically names a location in the +@uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}. +A recent catalog of location names appears in the +@uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time +Gateway}. A few non-@acronym{GNU} hosts require a colon before a +location name in a @env{TZ} setting, e.g., +@samp{TZ=":America/New_York"}. + +The @samp{tz} database includes a wide variety of locations ranging +from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but +if you are at sea and have your own private time zone, or if you are +using a non-@acronym{GNU} host that does not support the @samp{tz} +database, you may need to use a @acronym{POSIX} rule instead. Simple +@acronym{POSIX} rules like @samp{UTC0} specify a time zone without +daylight saving time; other rules can specify simple daylight saving +regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ}, +libc, The GNU C Library}. + +@node Authors of get_date +@section Authors of @code{get_date} + +@cindex authors of @code{get_date} + +@cindex Bellovin, Steven M. +@cindex Salz, Rich +@cindex Berets, Jim +@cindex MacKenzie, David +@cindex Meyering, Jim +@cindex Eggert, Paul +@code{get_date} was originally implemented by Steven M. Bellovin +(@email{smb@@research.att.com}) while at the University of North Carolina +at Chapel Hill. The code was later tweaked by a couple of people on +Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com}) +and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various +revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering, +Paul Eggert and others. + +@cindex Pinard, F. +@cindex Berry, K. +This chapter was originally produced by Fran@,{c}ois Pinard +(@email{pinard@@iro.umontreal.ca}) from the @file{get_date.y} source code, +and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).
deleted file mode 100644 --- a/doc/getdate.texi +++ /dev/null @@ -1,556 +0,0 @@ -@c GNU date syntax documentation - -@c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. - -@c Permission is granted to copy, distribute and/or modify this document -@c under the terms of the GNU Free Documentation License, Version 1.3 or -@c any later version published by the Free Software Foundation; with no -@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -@c Texts. A copy of the license is included in the ``GNU Free -@c Documentation License'' file as part of this distribution. - -@node Date input formats -@chapter Date input formats - -@cindex date input formats -@findex get_date - -First, a quote: - -@quotation -Our units of temporal measurement, from seconds on up to months, are so -complicated, asymmetrical and disjunctive so as to make coherent mental -reckoning in time all but impossible. Indeed, had some tyrannical god -contrived to enslave our minds to time, to make it all but impossible -for us to escape subjection to sodden routines and unpleasant surprises, -he could hardly have done better than handing down our present system. -It is like a set of trapezoidal building blocks, with no vertical or -horizontal surfaces, like a language in which the simplest thought -demands ornate constructions, useless particles and lengthy -circumlocutions. Unlike the more successful patterns of language and -science, which enable us to face experience boldly or at least -level-headedly, our system of temporal calculation silently and -persistently encourages our terror of time. - -@dots{} It is as though architects had to measure length in feet, width -in meters and height in ells; as though basic instruction manuals -demanded a knowledge of five different languages. It is no wonder then -that we often look into our own immediate past or future, last Tuesday -or a week from Sunday, with feelings of helpless confusion. @dots{} - ---- Robert Grudin, @cite{Time and the Art of Living}. -@end quotation - -This section describes the textual date representations that @sc{gnu} -programs accept. These are the strings you, as a user, can supply as -arguments to the various programs. The C interface (via the -@code{get_date} function) is not described here. - -@menu -* General date syntax:: Common rules. -* Calendar date items:: 19 Dec 1994. -* Time of day items:: 9:20pm. -* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}. -* Day of week items:: Monday and others. -* Relative items in date strings:: next tuesday, 2 years ago. -* Pure numbers in date strings:: 19931219, 1440. -* Seconds since the Epoch:: @@1078100502. -* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". -* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al. -@end menu - - -@node General date syntax -@section General date syntax - -@cindex general date syntax - -@cindex items in date strings -A @dfn{date} is a string, possibly empty, containing many items -separated by whitespace. The whitespace may be omitted when no -ambiguity arises. The empty string means the beginning of today (i.e., -midnight). Order of the items is immaterial. A date string may contain -many flavors of items: - -@itemize @bullet -@item calendar date items -@item time of day items -@item time zone items -@item day of the week items -@item relative items -@item pure numbers. -@end itemize - -@noindent We describe each of these item types in turn, below. - -@cindex numbers, written-out -@cindex ordinal numbers -@findex first @r{in date strings} -@findex next @r{in date strings} -@findex last @r{in date strings} -A few ordinal numbers may be written out in words in some contexts. This is -most useful for specifying day of the week items or relative items (see -below). Among the most commonly used ordinal numbers, the word -@samp{last} stands for @math{-1}, @samp{this} stands for 0, and -@samp{first} and @samp{next} both stand for 1. Because the word -@samp{second} stands for the unit of time there is no way to write the -ordinal number 2, but for convenience @samp{third} stands for 3, -@samp{fourth} for 4, @samp{fifth} for 5, -@samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8, -@samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and -@samp{twelfth} for 12. - -@cindex months, written-out -When a month is written this way, it is still considered to be written -numerically, instead of being ``spelled in full''; this changes the -allowed strings. - -@cindex language, in dates -In the current implementation, only English is supported for words and -abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first}, -@samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}. - -@cindex language, in dates -@cindex time zone item -The output of the @command{date} command -is not always acceptable as a date string, -not only because of the language problem, but also because there is no -standard meaning for time zone items like @samp{IST}. When using -@command{date} to generate a date string intended to be parsed later, -specify a date format that is independent of language and that does not -use time zone items other than @samp{UTC} and @samp{Z}. Here are some -ways to do this: - -@example -$ LC_ALL=C TZ=UTC0 date -Mon Mar 1 00:21:42 UTC 2004 -$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' -2004-03-01 00:21:42Z -$ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. -2004-02-29 16:21:42,692722128-0800 -$ date --rfc-2822 # a GNU extension -Sun, 29 Feb 2004 16:21:42 -0800 -$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. -2004-02-29 16:21:42 -0800 -$ date +'@@%s.%N' # %s and %N are GNU extensions. -@@1078100502.692722128 -@end example - -@cindex case, ignored in dates -@cindex comments, in dates -Alphabetic case is completely ignored in dates. Comments may be introduced -between round parentheses, as long as included parentheses are properly -nested. Hyphens not followed by a digit are currently ignored. Leading -zeros on numbers are ignored. - -Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are -rejected. In the typical case of a host that does not support leap -seconds, a time like @samp{23:59:60} is rejected even if it -corresponds to a valid leap second. - - -@node Calendar date items -@section Calendar date items - -@cindex calendar date item - -A @dfn{calendar date item} specifies a day of the year. It is -specified differently, depending on whether the month is specified -numerically or literally. All these strings specify the same calendar date: - -@example -1972-09-24 # @sc{iso} 8601. -72-9-24 # Assume 19xx for 69 through 99, - # 20xx for 00 through 68. -72-09-24 # Leading zeros are ignored. -9/24/72 # Common U.S. writing. -24 September 1972 -24 Sept 72 # September has a special abbreviation. -24 Sep 72 # Three-letter abbreviations always allowed. -Sep 24, 1972 -24-sep-72 -24sep72 -@end example - -The year can also be omitted. In this case, the last specified year is -used, or the current year if none. For example: - -@example -9/24 -sep 24 -@end example - -Here are the rules. - -@cindex @sc{iso} 8601 date format -@cindex date format, @sc{iso} 8601 -For numeric months, the @sc{iso} 8601 format -@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is -any positive number, @var{month} is a number between 01 and 12, and -@var{day} is a number between 01 and 31. A leading zero must be present -if a number is less than ten. If @var{year} is 68 or smaller, then 2000 -is added to it; otherwise, if @var{year} is less than 100, -then 1900 is added to it. The construct -@samp{@var{month}/@var{day}/@var{year}}, popular in the United States, -is accepted. Also @samp{@var{month}/@var{day}}, omitting the year. - -@cindex month names in date strings -@cindex abbreviations for months -Literal months may be spelled out in full: @samp{January}, -@samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June}, -@samp{July}, @samp{August}, @samp{September}, @samp{October}, -@samp{November} or @samp{December}. Literal months may be abbreviated -to their first three letters, possibly followed by an abbreviating dot. -It is also permitted to write @samp{Sept} instead of @samp{September}. - -When months are written literally, the calendar date may be given as any -of the following: - -@example -@var{day} @var{month} @var{year} -@var{day} @var{month} -@var{month} @var{day} @var{year} -@var{day}-@var{month}-@var{year} -@end example - -Or, omitting the year: - -@example -@var{month} @var{day} -@end example - - -@node Time of day items -@section Time of day items - -@cindex time of day item - -A @dfn{time of day item} in date strings specifies the time on a given -day. Here are some examples, all of which represent the same time: - -@example -20:02:00.000000 -20:02 -8:02pm -20:02-0500 # In @sc{est} (U.S. Eastern Standard Time). -@end example - -More generally, the time of day may be given as -@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is -a number between 0 and 23, @var{minute} is a number between 0 and -59, and @var{second} is a number between 0 and 59 possibly followed by -@samp{.} or @samp{,} and a fraction containing one or more digits. -Alternatively, -@samp{:@var{second}} can be omitted, in which case it is taken to -be zero. On the rare hosts that support leap seconds, @var{second} -may be 60. - -@findex am @r{in date strings} -@findex pm @r{in date strings} -@findex midnight @r{in date strings} -@findex noon @r{in date strings} -If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.} -or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and -@samp{:@var{minute}} may be omitted (taken to be zero). @samp{am} -indicates the first half of the day, @samp{pm} indicates the second -half of the day. In this notation, 12 is the predecessor of 1: -midnight is @samp{12am} while noon is @samp{12pm}. -(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm}, -as opposed to the old tradition derived from Latin -which uses @samp{12m} for noon and @samp{12pm} for midnight.) - -@cindex time zone correction -@cindex minutes, time zone correction by -The time may alternatively be followed by a time zone correction, -expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+} -or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number -of zone minutes. -The zone minutes term, @var{mm}, may be omitted, in which case -the one- or two-digit correction is interpreted as a number of hours. -You can also separate @var{hh} from @var{mm} with a colon. -When a time zone correction is given this way, it -forces interpretation of the time relative to -Coordinated Universal Time (@sc{utc}), overriding any previous -specification for the time zone or the local time zone. For example, -@samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours -ahead of @sc{utc} (e.g., India). -This is the best way to -specify a time zone correction by fractional parts of an hour. -The maximum zone correction is 24 hours. - -Either @samp{am}/@samp{pm} or a time zone correction may be specified, -but not both. - - -@node Time zone items -@section Time zone items - -@cindex time zone item - -A @dfn{time zone item} specifies an international time zone, indicated -by a small set of letters, e.g., @samp{UTC} or @samp{Z} -for Coordinated Universal -Time. Any included periods are ignored. By following a -non-daylight-saving time zone by the string @samp{DST} in a separate -word (that is, separated by some white space), the corresponding -daylight saving time zone may be specified. -Alternatively, a non-daylight-saving time zone can be followed by a -time zone correction, to add the two values. This is normally done -only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to -@samp{+05:30}. - -Time zone items other than @samp{UTC} and @samp{Z} -are obsolescent and are not recommended, because they -are ambiguous; for example, @samp{EST} has a different meaning in -Australia than in the United States. Instead, it's better to use -unambiguous numeric time zone corrections like @samp{-0500}, as -described in the previous section. - -If neither a time zone item nor a time zone correction is supplied, -time stamps are interpreted using the rules of the default time zone -(@pxref{Specifying time zone rules}). - - -@node Day of week items -@section Day of week items - -@cindex day of week item - -The explicit mention of a day of the week will forward the date -(only if necessary) to reach that day of the week in the future. - -Days of the week may be spelled out in full: @samp{Sunday}, -@samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday}, -@samp{Friday} or @samp{Saturday}. Days may be abbreviated to their -first three letters, optionally followed by a period. The special -abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for -@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are -also allowed. - -@findex next @var{day} -@findex last @var{day} -A number may precede a day of the week item to move forward -supplementary weeks. It is best used in expression like @samp{third -monday}. In this context, @samp{last @var{day}} or @samp{next -@var{day}} is also acceptable; they move one week before or after -the day that @var{day} by itself would represent. - -A comma following a day of the week item is ignored. - - -@node Relative items in date strings -@section Relative items in date strings - -@cindex relative items in date strings -@cindex displacement of dates - -@dfn{Relative items} adjust a date (or the current date if none) forward -or backward. The effects of relative items accumulate. Here are some -examples: - -@example -1 year -1 year ago -3 years -2 days -@end example - -@findex year @r{in date strings} -@findex month @r{in date strings} -@findex fortnight @r{in date strings} -@findex week @r{in date strings} -@findex day @r{in date strings} -@findex hour @r{in date strings} -@findex minute @r{in date strings} -The unit of time displacement may be selected by the string @samp{year} -or @samp{month} for moving by whole years or months. These are fuzzy -units, as years and months are not all of equal duration. More precise -units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7 -days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes, -@samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or -@samp{sec} worth one second. An @samp{s} suffix on these units is -accepted and ignored. - -@findex ago @r{in date strings} -The unit of time may be preceded by a multiplier, given as an optionally -signed number. Unsigned numbers are taken as positively signed. No -number at all implies 1 for a multiplier. Following a relative item by -the string @samp{ago} is equivalent to preceding the unit by a -multiplier with value @math{-1}. - -@findex day @r{in date strings} -@findex tomorrow @r{in date strings} -@findex yesterday @r{in date strings} -The string @samp{tomorrow} is worth one day in the future (equivalent -to @samp{day}), the string @samp{yesterday} is worth -one day in the past (equivalent to @samp{day ago}). - -@findex now @r{in date strings} -@findex today @r{in date strings} -@findex this @r{in date strings} -The strings @samp{now} or @samp{today} are relative items corresponding -to zero-valued time displacement, these strings come from the fact -a zero-valued time displacement represents the current time when not -otherwise changed by previous items. They may be used to stress other -items, like in @samp{12:00 today}. The string @samp{this} also has -the meaning of a zero-valued time displacement, but is preferred in -date strings like @samp{this thursday}. - -When a relative item causes the resulting date to cross a boundary -where the clocks were adjusted, typically for daylight saving time, -the resulting date and time are adjusted accordingly. - -The fuzz in units can cause problems with relative items. For -example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01, -because 2003-06-31 is an invalid date. To determine the previous -month more reliably, you can ask for the month before the 15th of the -current month. For example: - -@example -$ date -R -Thu, 31 Jul 2003 13:02:39 -0700 -$ date --date='-1 month' +'Last month was %B?' -Last month was July? -$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' -Last month was June! -@end example - -Also, take care when manipulating dates around clock changes such as -daylight saving leaps. In a few cases these have added or subtracted -as much as 24 hours from the clock, so it is often wise to adopt -universal time by setting the @env{TZ} environment variable to -@samp{UTC0} before embarking on calendrical calculations. - -@node Pure numbers in date strings -@section Pure numbers in date strings - -@cindex pure numbers in date strings - -The precise interpretation of a pure decimal number depends -on the context in the date string. - -If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no -other calendar date item (@pxref{Calendar date items}) appears before it -in the date string, then @var{yyyy} is read as the year, @var{mm} as the -month number and @var{dd} as the day of the month, for the specified -calendar date. - -If the decimal number is of the form @var{hh}@var{mm} and no other time -of day item appears before it in the date string, then @var{hh} is read -as the hour of the day and @var{mm} as the minute of the hour, for the -specified time of day. @var{mm} can also be omitted. - -If both a calendar date and a time of day appear to the left of a number -in the date string, but no relative item, then the number overrides the -year. - - -@node Seconds since the Epoch -@section Seconds since the Epoch - -If you precede a number with @samp{@@}, it represents an internal time -stamp as a count of seconds. The number can contain an internal -decimal point (either @samp{.} or @samp{,}); any excess precision not -supported by the internal representation is truncated toward minus -infinity. Such a number cannot be combined with any other date -item, as it specifies a complete time stamp. - -@cindex beginning of time, for @acronym{POSIX} -@cindex epoch, for @acronym{POSIX} -Internally, computer times are represented as a count of seconds since -an epoch---a well-defined point of time. On @acronym{GNU} and -@acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so -@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01 -00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other -@acronym{POSIX}-compliant systems support such times as an extension -to @acronym{POSIX}, using negative counts, so that @samp{@@-1} -represents 1969-12-31 23:59:59 @sc{utc}. - -Traditional Unix systems count seconds with 32-bit two's-complement -integers and can represent times from 1901-12-13 20:45:52 through -2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts -of seconds with nanosecond subcounts, and can represent all the times -in the known lifetime of the universe to a resolution of 1 nanosecond. - -On most hosts, these counts ignore the presence of leap seconds. -For example, on most hosts @samp{@@915148799} represents 1998-12-31 -23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00 -@sc{utc}, and there is no way to represent the intervening leap second -1998-12-31 23:59:60 @sc{utc}. - -@node Specifying time zone rules -@section Specifying time zone rules - -@vindex TZ -Normally, dates are interpreted using the rules of the current time -zone, which in turn are specified by the @env{TZ} environment -variable, or by a system default if @env{TZ} is not set. To specify a -different set of default time zone rules that apply just to one date, -start the date with a string of the form @samp{TZ="@var{rule}"}. The -two quote characters (@samp{"}) must be present in the date, and any -quotes or backslashes within @var{rule} must be escaped by a -backslash. - -For example, with the @acronym{GNU} @command{date} command you can -answer the question ``What time is it in New York when a Paris clock -shows 6:30am on October 31, 2004?'' by using a date beginning with -@samp{TZ="Europe/Paris"} as shown in the following shell transcript: - -@example -$ export TZ="America/New_York" -$ date --date='TZ="Europe/Paris" 2004-10-31 06:30' -Sun Oct 31 01:30:00 EDT 2004 -@end example - -In this example, the @option{--date} operand begins with its own -@env{TZ} setting, so the rest of that operand is processed according -to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31 -06:30} as if it were in Paris. However, since the output of the -@command{date} command is processed according to the overall time zone -rules, it uses New York time. (Paris was normally six hours ahead of -New York in 2004, but this example refers to a brief Halloween period -when the gap was five hours.) - -A @env{TZ} value is a rule that typically names a location in the -@uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}. -A recent catalog of location names appears in the -@uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time -Gateway}. A few non-@acronym{GNU} hosts require a colon before a -location name in a @env{TZ} setting, e.g., -@samp{TZ=":America/New_York"}. - -The @samp{tz} database includes a wide variety of locations ranging -from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but -if you are at sea and have your own private time zone, or if you are -using a non-@acronym{GNU} host that does not support the @samp{tz} -database, you may need to use a @acronym{POSIX} rule instead. Simple -@acronym{POSIX} rules like @samp{UTC0} specify a time zone without -daylight saving time; other rules can specify simple daylight saving -regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ}, -libc, The GNU C Library}. - -@node Authors of get_date -@section Authors of @code{get_date} - -@cindex authors of @code{get_date} - -@cindex Bellovin, Steven M. -@cindex Salz, Rich -@cindex Berets, Jim -@cindex MacKenzie, David -@cindex Meyering, Jim -@cindex Eggert, Paul -@code{get_date} was originally implemented by Steven M. Bellovin -(@email{smb@@research.att.com}) while at the University of North Carolina -at Chapel Hill. The code was later tweaked by a couple of people on -Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com}) -and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various -revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering, -Paul Eggert and others. - -@cindex Pinard, F. -@cindex Berry, K. -This chapter was originally produced by Fran@,{c}ois Pinard -(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code, -and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).
--- a/gnulib-tool +++ b/gnulib-tool @@ -5324,7 +5324,7 @@ ) || func_exit 1 fi # Need to run configure and make once, to create built files that are to be - # distributed (such as getdate.c). + # distributed (such as get_date.c). sed_remove_make_variables='s,[$]([A-Za-z0-9_]*),,g' # Extract the value of "CLEANFILES += ..." and "MOSTLYCLEANFILES += ...". cleaned_files=`sed -e "$sed_remove_backslash_newline" < "$testdir/$sourcebase/Makefile.am" \
--- a/m4/bison.m4 +++ b/m4/bison.m4 @@ -1,4 +1,4 @@ -# serial 5 +# serial 6 # Copyright (C) 2002, 2005, 2009, 2010 Free Software Foundation, Inc. # This file is free software; the Free Software Foundation @@ -7,7 +7,7 @@ AC_DEFUN([gl_BISON], [ - # getdate.y works with bison only. + # get_date.y works with bison only. : ${YACC='bison -y'} dnl dnl Declaring YACC & YFLAGS precious will not be necessary after GNULIB
--- a/m4/get_date.m4 +++ b/m4/get_date.m4 @@ -1,4 +1,4 @@ -# getdate.m4 serial 17 +# get_date.m4 serial 17 dnl Copyright (C) 2002-2006, 2008-2010 Free Software Foundation, Inc. dnl This file is free software; the Free Software Foundation dnl gives unlimited permission to copy and/or distribute it, @@ -30,7 +30,7 @@ AC_REQUIRE([AM_STDBOOL_H]) AC_REQUIRE([gl_TIMESPEC]) - dnl Prerequisites of lib/getdate.y. + dnl Prerequisites of lib/get_date.y. AC_REQUIRE([gl_BISON]) AC_REQUIRE([gl_C_COMPOUND_LITERALS]) AC_STRUCT_TIMEZONE