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

[Assaf Gordon]

Attached yet another improvement, this time supporting detailed timezone 
information.

Examples below, all examples run on a computer with default timezone of 
EST=-05:00 .

Comments welcomed,
 - assaf

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

Explaining the 'bug' ( http://debbugs.gnu.org/22439 ) now becomes:
===
$ ./src/date --debug -d '@0' +%X
date: parsed timespec part: timespec=0 seconds
date: warning: default input timezone: -05:00
date: final epoch-seconds: 0.000000000
date: final date: '(Y-M-D) 1970-01-01 00:00:00' UTC
date: final date: '(Y-M-D) 1969-12-31 19:00:00' (local TZ=-05:00)
19:00:00
===

versus:

===
$ ./src/date --debug -d '1970/1/1' +%X
date: warning: value 1970 has 4 digits. Assuming YYYY/MM/DD
date: parsed date part: (Y-M-D) 1970-01-01 
date: warning: default input timezone: -05:00
date: warning: using midnight as starting time: 00:00:00
date: starting date/time: '(Y-M-D) 1970-01-01 00:00:00 TZ=-05:00'
date: '(Y-M-D) 1970-01-01 00:00:00 TZ=-05:00' = 18000 epoch-seconds
date: final epoch-seconds: 18000.000000000
date: final date: '(Y-M-D) 1970-01-01 05:00:00' UTC
date: final date: '(Y-M-D) 1970-01-01 00:00:00' (local TZ=-05:00)
00:00:00
===

More complicated scenarios:

=== Using TZ string overrides default TZ ===

$ ./src/date --debug -d 'TZ="Asia/Tokyo" 1970/1/1' +%X
date: warning: default input timezome modfied by explicit TZ value
date: warning: value 1970 has 4 digits. Assuming YYYY/MM/DD
date: parsed date part: (Y-M-D) 1970-01-01 
date: warning: default input timezone: +09:00
date: warning: using midnight as starting time: 00:00:00
date: starting date/time: '(Y-M-D) 1970-01-01 00:00:00 TZ=+09:00'
date: '(Y-M-D) 1970-01-01 00:00:00 TZ=+09:00' = -32400 epoch-seconds
date: final epoch-seconds: -32400.000000000
date: final date: '(Y-M-D) 1969-12-31 15:00:00' UTC
date: final date: '(Y-M-D) 1969-12-31 10:00:00' (local TZ=-05:00)
10:00:00

===

=== Using explicit timezone overrides everything else ===

$ ./src/date --debug -d 'TZ="Asia/Tokyo" 1970/1/1 00:00:00 +06:00' +%X
date: warning: default input timezome modfied by explicit TZ value
date: warning: value 1970 has 4 digits. Assuming YYYY/MM/DD
date: parsed date part: (Y-M-D) 1970-01-01 
date: parsed time part: 00:00:00 TZ=+06:00
date: warning: default input timezone: +09:00
date: warning: explicit timezone overrides default: +06:00
date: using specified time as starting value: '00:00:00'
date: starting date/time: '(Y-M-D) 1970-01-01 00:00:00 TZ=+06:00'
date: '(Y-M-D) 1970-01-01 00:00:00 TZ=+06:00' = -32400 epoch-seconds
date: after timezone adjustment (+360 minutes),
date:     new time = -21600 epoch-seconds
date: final epoch-seconds: -21600.000000000
date: final date: '(Y-M-D) 1969-12-31 18:00:00' UTC
date: final date: '(Y-M-D) 1969-12-31 13:00:00' (local TZ=-05:00)
13:00:00
====

=== Daylight-saving issues ===

$ ./src/date --debug -d "2006-04-02 02:30:00"
date: parsed date part: (Y-M-D) 2006-04-02 
date: parsed time part: 02:30:00 
date: warning: default input timezone: -05:00
date: using specified time as starting value: '02:30:00'
date: error: invalid date/time value:
date:     user provided time: '(Y-M-D) 2006-04-02 02:30:00 TZ=-05:00'
date:        normalized time: '(Y-M-D) 2006-04-02 03:30:00 TZ=-05:00'
date:                                             --      
date:      possible reasons:
date:        non-existing due to daylight-saving time;
date:        numeric values overflow;
date:        missing timezone;
./src/date: invalid date ‘2006-04-02 02:30:00’

$ ./src/date --debug -d "2006-04-02 02:30:00 +01:00"
date: parsed date part: (Y-M-D) 2006-04-02 
date: parsed time part: 02:30:00 TZ=+01:00
date: warning: default input timezone: -05:00
date: warning: explicit timezone overrides default: +01:00
date: using specified time as starting value: '02:30:00'
date: starting date/time: '(Y-M-D) 2006-04-02 02:30:00 TZ=+01:00'
date: '(Y-M-D) 2006-04-02 02:30:00 TZ=+01:00' = 1143941400 epoch-seconds
date: after timezone adjustment (+60 minutes),
date:     new time = 1143941400 epoch-seconds
date: final epoch-seconds: 1143941400.000000000
date: final date: '(Y-M-D) 2006-04-02 01:30:00' UTC
date: final date: '(Y-M-D) 2006-04-01 20:30:00' (local TZ=-05:00)
Sat Apr  1 20:30:00 EST 2006

===