suggested feautre: "date --debug" - print date parsing diagnostics

[Assaf Gordon]

Hello,

What do you think about adding a "--debug" option to 'date' ?
This will hopefully help users to diagnose incorrect usage with "date -d" (but, 
will add a bit of bloat to gnulib).

Attached is a rough proof-of-concept patch (mostly for gnulib, but since the 
user-facing chances will be in coreutils, I'm sending it here).

The patch adds the following:

1. Global option in gnulib's parse-datetime.y to enable debug (could be changed 
to a parameter)

2. two functions (debug_print_pc and debug_print_rel) to print the currently 
parsed value of the date/time or relative date/time .

3. printing the current date/time value on every successful parsed part.

4. printing an informative message on every logic error (i.e. before "goto 
fail").

5. printing informative warning for common mis-use (e.g. adding days but not 
specifying 12pm, or adding months/years without specifying the 15th of the 
month).


Output examples below (the wording of the messages can be improved, of course).

The 'gnulib' patch needs to be applied in the gnulib directory (until if/when 
it is applied to gnulib directly):

  $ git clone git://git.sv.gnu.org/coreutils.git
  $ cd coreutils
  $ ./bootstrap
  $ ./configure
  $ git am < coreutils-debug-date.patch
  $ ( cd gnulib ; git am < ../gnulib-debug-date.patch )
  $ make src/date

Examples below.

Comments welcomed.
 - Assaf

=====

$ ./src/date --debug -d '2014-09-06T13:45:00'
date: parsed datetime part: (Y-M-D) 2014-09-06 13:45:00 
Sat Sep  6 13:45:00 EDT 2014

$ ./src/date --debug -d '2014-09-06 13:45:00'
date: parsed date part: (Y-M-D) 2014-09-06 
date: parsed time part: (Y-M-D) 2014-09-06 13:45:00 
Sat Sep  6 13:45:00 EDT 2014

$ ./src/date --debug -d '2014-09-06 13:45:00 +02:00'
date: parsed date part: (Y-M-D) 2014-09-06 
date: parsed time part: (Y-M-D) 2014-09-06 13:45:00 TimeZone=+2:00h
Sat Sep  6 07:45:00 EDT 2014

$ ./src/date --debug -d '2014-09-06 13:45:00 +B'
date: parsed date part: (Y-M-D) 2014-09-06 
date: parsed time part: (Y-M-D) 2014-09-06 13:45:00 
date: parsed zone part: (Y-M-D) 2014-09-06 13:45:00 TimeZone=-2:00h
Sat Sep  6 11:45:00 EDT 2014x

$ ./src/date --debug -d 'next tues'
date: parsed day part: day-ordinal=1 day-number=2 
date: new start date: 2016-01-26 (based on ordinal=1 day-of-week=2)
Tue Jan 26 00:00:00 EST 2016

$ ./src/date --debug -d 'now + 5 months 2 years'
date: parsed relative part: today/this/now
date: parsed relative part: +5 month(s) 
date: parsed relative part: +2 year(s) +5 month(s) 
Thu Jun 21 02:07:36 EDT 2018

$ ./src/date --debug -d '01-03-2001'
date: parsed date part: (Y-M-D) 0001-03-2001 
date: error: invalid date, possibly due to incorrect day (2001) for this month 
(3), daylight-saving time, or missing timezone
./src/date: invalid date ‘01-03-2001’

$ ./src/date --debug -d '01-09'
date: parsed time part: 01:00:00 TimeZone=-9:00h
Thu Jan 21 05:00:00 EST 2016

$ ./src/date --debug -d '04:00 + 3 days'
date: parsed time part: 04:00:00 TimeZone=+3:00h
date: parsed relative part: +1 day(s) 
Thu Jan 21 20:00:00 EST 2016

$ ./src/date --debug -d '2016-04-05 + 5 days'
date: parsed date part: (Y-M-D) 2016-04-05 
date: parsed relative part: +5 day(s) 
date: warning: when adding relative days, it is recommended to specify 12:00pm
Sun Apr 10 00:00:00 EDT 2016

$ ./src/date --debug -d 'next friday + 2 days'
date: parsed day part: day-ordinal=1 day-number=5 
date: parsed relative part: +2 day(s) 
date: new start date: 2016-01-22 (based on ordinal=1 day-of-week=5)
date: warning: when adding relative days, it is recommended to specify 12:00pm
Sun Jan 24 00:00:00 EST 2016


$ ./src/date --debug -d '13:30 05:00'
date: parsed time part: 13:30:00 
date: parsed time part: 05:00:00 
date: error: seen multiple time parts
./src/date: invalid date ‘13:30 05:00’

$ ./src/date --debug -d '13:30 +05:00'
date: parsed time part: 13:30:00 TimeZone=+5:00h
Thu Jan 21 03:30:00 EST 2016

$ ./src/date --debug -d '19:00am'
date: parsed time part: 19:00:00 
date: error: invalid hour 19am
./src/date: invalid date ‘19:00am’

$ ./src/date --debug -d 'Aug 2015 + 5 months'
date: parsed date part: (Y-M-D) 2016-08-2015 
date: parsed relative part: +5 month(s) 
date: error: invalid date, possibly due to incorrect day (2015) for this month 
(8), daylight-saving time, or missing timezone
./src/date: invalid date ‘Aug 2015 + 5 months’

$ ./src/date --debug -d '2015-08 + 5 months'
date: parsed date part: (Y-M-D) 2015-08--5 
date: parsed relative part: +1 month(s) 
date: error: invalid date, possibly due to incorrect day (-5) for this month 
(8), daylight-saving time, or missing timezone
./src/date: invalid date ‘2015-08 + 5 months’

$ ./src/date --debug -d '2015-08-01 + 5 months'
date: parsed date part: (Y-M-D) 2015-08-01 
date: parsed relative part: +5 month(s) 
date: warning: when adding relative months/years, it is recommended to specify 
the 15th of the months
Fri Jan  1 00:00:00 EST 2016

coreutils-debug-date.patch
Description: Binary data

gnulib-debug-parse-date.patch
Description: Binary data