dates interface

[stuckyb]

We've recently discussed the interface for specifying dates and landed on the following:

• Single dates and simple date ranges are specified with the parameter dates. This parameter can express:
  • one or more individual dates in "YYYY", "YYYY-MM", or "YYYY-MM-DD" format: 1980-01-12, 1980-01-12,1990-02-14, 1980,1982,1990
  • simple date ranges: 1980:1990, 1980-01-12:1981-01-12
  • combinations of single dates and simple ranges:
• More complicated date patterns are specified with the parameters years, months, and days (YMD). These parameters can express:
  • single values: 1980, 4, 1980,1981, 4,8,10
  • ranges: 1980:1990, 4:20
  • ranges with a custom increment: 1980:1990+5, 4:20+2
  • combinations of the above: 1,10:20+2,28

The last day in a month or year can be specified by using N instead of an integer. For example: 1,10,N, 1:N, 20:N.

Ranges are inclusive of their endpoints unless the endpoint does not correspond with the step size increment.

If dates is provided, the other date parameters will be ignored.

Date grain is inferred from the specificity of dates or, for the YMD parameters, as follows:

• If years is used by itself, the grain is annual.
• If years and months are used together, the grain is monthly.
• If years and days are used together, the grain is daily and days is interpreted as day of year.
• If years, months, and days are used together, the grain is daily and days is interpreted as day of month.
• All other YMD parameter combinations are invalid.

[stuckyb]

This is fully implemented as described by f82dc11d1b225d01e and earlier commits. I am leaving this open for now because we need to update the documentation.

[stuckyb]

More changes after further discussion: replacing date_start and date_end with a single dates parameter and using : as the sequence operator. I've updated the initial comment accordingly.

[stuckyb]

The changes described in the previous comment are now fully implemented. One other enhancement I'd like to add before closing this is to make leading 0s in dates optional. E.g., either "2020-1" or "2020-01" would be acceptable. That would be a bit more user-friendly and make the dates number formatting consistent with months and days, where leading 0s are not required.

[stuckyb]

This is now complete with 8c2134323c181c0e42. I will close this issue and create a separate issue for user documentation.