Parse options & other features

[lukescott]

We use the cron package at the company I work for, and we've made some modifications that were needed for our backend. I have four features separated into separate branches, and I'm wondering if you would be interested in merging these.

1. Parse options https://github.com/webconnex/cron/tree/parser-options
   This adds Parser and NewParser with the ability to:

   • Select which fields are included. So you can exclude seconds, or any other field you don't want to use.
   • Set other options that might be useful, like making certain assumptions about the schedule.

   The Parse function now looks like this:

   var defaultParser = NewParser(
       Second | Minute | Hour | Dom | Month | DowOptinal | Descriptor,
   )
   
   // Parse returns a new crontab schedule representing the given spec.
   // It returns a descriptive error if the spec is not valid.
   //
   // It accepts
   //   - Full crontab specs, e.g. "* * * * * ?"
   //   - Descriptors, e.g. "@midnight", "@every 1h30m"
   func Parse(spec string) (_ Schedule, err error) {
       return defaultParser.Parse(spec)
   }

   This could be a resolution for Cron Format not the same as Cron Spec #58. All you would need to do is remove Second and it would be spec compliant. But for those who need it, they can create a new parser with the option.

   I'm not sure about Dow being optional and being "spec complaint" - but there are two options for this - Dow and DowOptional which are interchangeable - one makes it required, the other allows you to omit it.

2. Week year (built upon parser-options) https://github.com/webconnex/cron/tree/wy-field

   Adds another option after Dow that specifies the week of the year. This allows you to do bi-weekly schedules. It's used in conjunction with Dow.

3. Year field (built upon wy-field + parser-options) https://github.com/webconnex/cron/tree/year-field

   Adds year field after week year. Range 2000 - 2099. Utilizes multi-bits. Can change to larger range, it just uses a larger slice (current size is 2).

4. Approx Dom (built upon parser-options) https://github.com/webconnex/cron/tree/approx-date

   Adds a ~ symbol to be used at the beginning of a field (currently only supported for Dom) to specify approximate. If, for example, you say 31 and there are only 30 days in the target month, Next will choose the 30th. Or the 28th/29th in February.

   This is similar to L or L-1 in quartz, but differs from L-1 in that we don't want "the second to last day" we want a specific day in the month if it exists, but fall back to an earlier day if it doesn't. So L-1 would always land on the 30th, 28th (leap year Feb), or 27th (non-leap year Feb). ~30 would be the 30th, 29th (leap year Feb), and 28th (non-leap year Feb).

   An ApproxDay parser option was added to allow you to say "always assume approx date" without having to specify ~. In our case we always want this option in our system, while others may want to specify it in the schedule specifically.

The naming of the parser options could probably use an adjustment. And there may be some room for some better tests. I have added some for week year and approx dom. And the documentation would have to be updated. If interested, please let me know which areas need some improvement.

I also have plans to add L and # options from quartz - not sure how to approach those yet. Those options are probably further down pipe for me as the above features were to fill an immediate need for us.

I'm also planning on taking another stab at DST and not skipping / repeating. I had a PR for that a while back - and there was a comment about it being supported now - but the docs doesn't indicate that. I think I can also handle that in a less confusing way this time around :).

[lukescott]

@robfig

[lukescott]

Closing this. I'll send individual PR's for each feature's consideration.