# cronparse

Parse and calculate different times related to Unix cron expressions

Parse Unix cron expressions and calculate things like:

- whether the expression is valid, as a
`bool`

- the next time the expression will run, as a
`DateTime`

- the last time the expression would have run, as a
`DateTime`

- the duration until the next time the expression will run, as a
`Duration`

- the duration since the last time the expression would have run, as a negative
`Duration`

## Usage

```
void main() {
// validate a cron expression
final valid = isValid("54 2-3,4-9 */3 FEB MON-FRI");
print(valid); // true
// calculate times based on a cron expression
final time = DateTime.parse("2019-11-23 16:00:00");
var cron = Cron("0 22 * * *");
print(cron.nextRelativeTo(time)); // "2019-11-23 22:00:00.000"
print(cron.untilNextRelativeTo(time) == Duration(hours: 6)); // true
cron = Cron("*/15 * * * *");
print(cron.previousRelativeTo(time)); // "2019-11-23 15:45:00.000"
print(cron.sincePreviousRelativeTo(time) == Duration(minutes: -15)); // true
}
```

## Cron expression matching strategy

### High-level explanation on matching

- if the expression is a predefined nickname, translate it to the relevant actual expression. note: this library does not parse the
`@reboot`

nickname. - tokenize the expression to each part (minute, hour, day of month, month, day of week)
- test each of these tokens to match
- token values can be in a few forms:
- an asterisk (
`*`

): this always matches - an asterisk with skips (
`*/15`

): iterate through the valid range for the field, incrementing by the skip. if any of these match, the expression matches. - exact value (
`48`

,`feb`

,`WED`

): match these exactly - range of values without skips (
`5-9`

): iterate through the range, starting at the lower bound and ending at the higher bound, incrementing by 1. if any of these match, the value matches - range of values with skip (
`20-30/2`

): iterate through the range, starting at the lower bound and ending at the higher bound, incrementing by the skip value. if any of these match, the value matches. - set of values or ranges (
`1,2,3`

,`5-10,45-50`

): test each value in the set using the above strategy. if any of the member values match, the value matches.

- an asterisk (

- token values can be in a few forms:
- iff all tokens match, the expression matches

`@reboot`

This library is focused on temporal calculation for cron expressions. The `@reboot`

nickname is shorthand for "exactly once after reboot." Since the `@reboot`

nickname is not a temporal representation, it is not handled by this library.

## Links

## Libraries

- cronparse
- Parse and calculate different times related to Unix cron expressions