first commit

cronexpression.go

@@ -0,0 +1,726 @@
+/*!
+ * Copyright 2013 Raymond Hill
+ *
+ * Project: github.com/gorhill/gocronexpression
+ * File: cronexpression.go
+ * Version: 1.0
+ * License: GPL v3 see <https://www.gnu.org/licenses/gpl.html>
+ *
+ */
+
+package cronexpression
+
+/******************************************************************************/
+
+import (
+    "regexp"
+    "sort"
+    "strconv"
+    "strings"
+    "time"
+)
+
+/******************************************************************************/
+
+// A CronExpression represents a specific cron expression as defined on
+// Wikipedia: https://en.wikipedia.org/wiki/Cron#CRON_expression
+//
+type CronExpression struct {
+    Expression             string
+    secondList             []int
+    minuteList             []int
+    hourList               []int
+    daysOfMonth            map[int]bool
+    workdaysOfMonth        map[int]bool
+    lastDayOfMonth         bool
+    daysOfMonthRestricted  bool
+    actualDaysOfMonthList  []int
+    monthList              []int
+    daysOfWeek             map[int]bool
+    specificWeekDaysOfWeek map[int]bool
+    lastWeekDaysOfWeek     map[int]bool
+    daysOfWeekRestricted   bool
+    yearList               []int
+}
+
+/******************************************************************************/
+
+var noMatchTime = time.Date(2100, 7, 1, 0, 0, 0, 0, time.UTC)
+
+/******************************************************************************/
+
+// NewCronExpression() returns a new CronExpression pointer. It expects
+// a well-formed cron expression. If a malformed cron expression is
+// supplied, the result is undefined.
+func NewCronExpression(cronLine string) *CronExpression {
+    cronLineNormalized := cronNormalize(cronLine)
+
+    // Split into fields
+    cronFields := regexp.MustCompile(`\s+`).Split(cronLineNormalized, -1)
+
+    // Our cron expression parser expects 7 fields:
+    //    second minute hour dayofmonth month dayofweek year
+    // Standard cron is 6 fields with year field being optional
+    //           minute hour dayofmonth month dayofweek {year}
+    // Thus...
+    // If we have 5 fields, append wildcard year field
+    if len(cronFields) < 6 {
+        cronFields = append(cronFields, "*")
+    }
+    // If we have 6 fields, prepend match-once second field
+    if len(cronFields) < 7 {
+        cronFields = append(cronFields, "")
+        copy(cronFields[1:], cronFields[0:])
+        cronFields[0] = "0"
+    }
+    // We should have 7 fields at this point
+    if len(cronFields) != 7 {
+        panic("Malformed cron expression\n")
+    }
+
+    // Generic parser can be used for most fields
+    cronExpr := &CronExpression{
+        Expression: cronLine,
+        secondList: genericFieldParse(cronFields[0], 0, 59),
+        minuteList: genericFieldParse(cronFields[1], 0, 59),
+        hourList:   genericFieldParse(cronFields[2], 0, 23),
+        monthList:  genericFieldParse(cronFields[4], 1, 12),
+        yearList:   genericFieldParse(cronFields[6], 1970, 2099),
+    }
+
+    // Days of month/days of week is a bit more complicated, due
+    // to their extended syntax, and the fact that days per
+    // month is a variable quantity, and relation between
+    // days of week and days of month depends on the month/year.
+    cronExpr.dayofmonthFieldParse(cronFields[3])
+    cronExpr.dayofweekFieldParse(cronFields[5])
+
+    return cronExpr
+}
+
+/******************************************************************************/
+
+// NextTimeFromCronString() returns the time stamp following fromTime which
+// satisfies the cron expression cronLine. If no matching time stamp is found,
+// using NoMatch() with the returned time stamp as argument will return true.
+//
+// If the same cron expression must be used repeatedly, it is better to use
+// NewCronExpression() in order to avoid overhead of cron expression parsing.
+func NextTimeFromCronString(cronLine string, fromTime time.Time) time.Time {
+    cronexpr := NewCronExpression(cronLine)
+    return cronexpr.NextTime(fromTime)
+}
+
+/******************************************************************************/
+
+// NextTimeNFromCronString() returns the n time stamps following fromTime which
+// satisfy the cron expression cronLine. An empty list is returned if
+// there is no matching time stamp.
+//
+// If the same cron expression must be used repeatedly, it is better to use
+// NewCronExpression() in order to avoid overhead of cron expression parsing.
+func NextTimeNFromCronString(cronLine string, fromTime time.Time, n int) []time.Time {
+    cronexpr := NewCronExpression(cronLine)
+    return cronexpr.NextTimeN(fromTime, n)
+}
+
+/******************************************************************************/
+
+// CronExpression.NextTime() returns the time stamp following fromTime which
+// satisfies the cron expression. If no matching time stamp is found,
+// using NoMatch() with the returned time stamp as argument will return true.
+func (cronexpr *CronExpression) NextTime(fromTime time.Time) time.Time {
+    // Special case
+    if NoMatch(fromTime) {
+        return fromTime
+    }
+
+    // First we need to ensure supplied time stamp matches
+    // the cron expression. If not, this means the supplied time
+    // stamp might be between matching time stamps, thus we move
+    // to closest matching time stamp without changing time stamp
+
+    // year
+    v := fromTime.Year()
+    i := sort.SearchInts(cronexpr.yearList, v)
+    if i == len(cronexpr.yearList) {
+        return noMatchTime
+    }
+    if v != cronexpr.yearList[i] {
+        return cronexpr.nextYear(fromTime)
+    }
+    // month
+    v = int(fromTime.Month())
+    i = sort.SearchInts(cronexpr.monthList, v)
+    if i == len(cronexpr.monthList) {
+        return cronexpr.nextYear(fromTime)
+    }
+    if v != cronexpr.monthList[i] {
+        return cronexpr.nextMonth(fromTime)
+    }
+
+    cronexpr.actualDaysOfMonthList = cronexpr.calculateActualDaysOfMonth(fromTime.Year(), int(fromTime.Month()))
+    if len(cronexpr.actualDaysOfMonthList) == 0 {
+        return cronexpr.nextMonth(fromTime)
+    }
+
+    // day of month
+    v = fromTime.Day()
+    i = sort.SearchInts(cronexpr.actualDaysOfMonthList, v)
+    if i == len(cronexpr.actualDaysOfMonthList) {
+        return cronexpr.nextMonth(fromTime)
+    }
+    if v != cronexpr.actualDaysOfMonthList[i] {
+        return cronexpr.nextDayOfMonth(fromTime)
+    }
+    // hour
+    v = fromTime.Hour()
+    i = sort.SearchInts(cronexpr.hourList, v)
+    if i == len(cronexpr.hourList) {
+        return cronexpr.nextDayOfMonth(fromTime)
+    }
+    if v != cronexpr.hourList[i] {
+        return cronexpr.nextHour(fromTime)
+    }
+    // minute
+    v = fromTime.Minute()
+    i = sort.SearchInts(cronexpr.minuteList, v)
+    if i == len(cronexpr.minuteList) {
+        return cronexpr.nextHour(fromTime)
+    }
+    if v != cronexpr.minuteList[i] {
+        return cronexpr.nextMinute(fromTime)
+    }
+    // second
+    v = fromTime.Second()
+    i = sort.SearchInts(cronexpr.secondList, v)
+    if i == len(cronexpr.secondList) {
+        return cronexpr.nextMinute(fromTime)
+    }
+
+    // If we reach this point, there is nothing better to do
+    // than to move to the next second
+
+    return cronexpr.nextSecond(fromTime)
+}
+
+/******************************************************************************/
+
+// CronExpression.NextTimeN() returns an array of n time stamps following
+// fromTime which satisfy the cron expression. An empty list is returned if
+// there is no matching time stamp.
+func (cronexpr *CronExpression) NextTimeN(fromTime time.Time, n int) []time.Time {
+    if n <= 0 {
+        panic("CronExpression.NextTimeN(): invalid count")
+    }
+    nextTimes := make([]time.Time, 0)
+    fromTime = cronexpr.NextTime(fromTime)
+    for {
+        if NoMatch(fromTime) {
+            break
+        }
+        nextTimes = append(nextTimes, fromTime)
+        n -= 1
+        if n == 0 {
+            break
+        }
+        fromTime = cronexpr.nextSecond(fromTime)
+    }
+    return nextTimes
+}
+
+/******************************************************************************/
+
+// NoMatch() returns whether t is a valid time stamp, from CronExpression point
+// of view.
+func NoMatch(t time.Time) bool {
+    // https://en.wikipedia.org/wiki/Cron#CRON_expression: 1970–2099
+    return t.Year() >= 2100
+}
+
+/******************************************************************************/
+
+func (cronexpr *CronExpression) nextYear(t time.Time) time.Time {
+    // Find index at which item in list is greater or equal to
+    // candidate year
+    i := sort.SearchInts(cronexpr.yearList, t.Year()+1)
+    if i == len(cronexpr.yearList) {
+        return noMatchTime
+    }
+    // Year changed, need to recalculate actual days of month
+    cronexpr.actualDaysOfMonthList = cronexpr.calculateActualDaysOfMonth(cronexpr.yearList[i], cronexpr.monthList[0])
+    if len(cronexpr.actualDaysOfMonthList) == 0 {
+        return cronexpr.nextMonth(time.Date(
+            cronexpr.yearList[i],
+            time.Month(cronexpr.monthList[0]),
+            1,
+            cronexpr.hourList[0],
+            cronexpr.minuteList[0],
+            cronexpr.secondList[0],
+            0,
+            time.Local))
+    }
+    return time.Date(
+        cronexpr.yearList[i],
+        time.Month(cronexpr.monthList[0]),
+        cronexpr.actualDaysOfMonthList[0],
+        cronexpr.hourList[0],
+        cronexpr.minuteList[0],
+        cronexpr.secondList[0],
+        0,
+        time.Local)
+}
+
+/******************************************************************************/
+
+func (cronexpr *CronExpression) nextMonth(t time.Time) time.Time {
+    // Find index at which item in list is greater or equal to
+    // candidate month
+    i := sort.SearchInts(cronexpr.monthList, int(t.Month())+1)
+    if i == len(cronexpr.monthList) {
+        return cronexpr.nextYear(t)
+    }
+    // Month changed, need to recalculate actual days of month
+    cronexpr.actualDaysOfMonthList = cronexpr.calculateActualDaysOfMonth(t.Year(), cronexpr.monthList[i])
+    if len(cronexpr.actualDaysOfMonthList) == 0 {
+        return cronexpr.nextMonth(time.Date(
+            t.Year(),
+            time.Month(cronexpr.monthList[i]),
+            1,
+            cronexpr.hourList[0],
+            cronexpr.minuteList[0],
+            cronexpr.secondList[0],
+            0,
+            time.Local))
+    }
+
+    return time.Date(
+        t.Year(),
+        time.Month(cronexpr.monthList[i]),
+        cronexpr.actualDaysOfMonthList[0],
+        cronexpr.hourList[0],
+        cronexpr.minuteList[0],
+        cronexpr.secondList[0],
+        0,
+        time.Local)
+}
+
+/******************************************************************************/
+
+func (cronexpr *CronExpression) calculateActualDaysOfMonth(year, month int) []int {
+    actualDaysOfMonthMap := make(map[int]bool)
+    timeOrigin := time.Date(year, time.Month(month), 1, 0, 0, 0, 0, time.UTC)
+    lastDayOfMonth := timeOrigin.AddDate(0, 1, -1).Day()
+
+    // As per crontab man page (http://linux.die.net/man/5/crontab#):
+    //  "The day of a command's execution can be specified by two
+    //  "fields - day of month, and day of week. If both fields are
+    //  "restricted (ie, aren't *), the command will be run when
+    //  "either field matches the current time"
+    if cronexpr.daysOfMonthRestricted || cronexpr.daysOfWeekRestricted == false {
+        // Last day of month
+        if cronexpr.lastDayOfMonth {
+            actualDaysOfMonthMap[lastDayOfMonth] = true
+        }
+        // Days of month
+        for v, _ := range cronexpr.daysOfMonth {
+            // Ignore days beyond end of month
+            if v <= lastDayOfMonth {
+                actualDaysOfMonthMap[v] = true
+            }
+        }
+        // Work days of month
+        // As per Wikipedia: month boundaries are not crossed.
+        for v, _ := range cronexpr.workdaysOfMonth {
+            // Ignore days beyond end of month
+            if v <= lastDayOfMonth {
+                // If saturday, then friday
+                if timeOrigin.AddDate(0, 0, v-1).Weekday() == time.Saturday {
+                    if v > 1 {
+                        v -= 1
+                    } else {
+                        v += 2
+                    }
+                    // If sunday, then monday
+                } else if timeOrigin.AddDate(0, 0, v-1).Weekday() == time.Sunday {
+                    if v < lastDayOfMonth {
+                        v += 1
+                    } else {
+                        v -= 2
+                    }
+                }
+                actualDaysOfMonthMap[v] = true
+            }
+        }
+    }
+
+    if cronexpr.daysOfWeekRestricted {
+        // How far first sunday is from first day of month
+        offset := 7 - int(timeOrigin.Weekday())
+        // days of week
+        //  offset : (7 - day_of_week_of_1st_day_of_month)
+        //  target : (7 * week_of_month) + (offset + day_of_week) % 7 + 1
+        for w := 0; w <= 4; w += 1 {
+            for v, _ := range cronexpr.daysOfWeek {
+                v := 1 + w*7 + (offset+v)%7
+                if v <= lastDayOfMonth {
+                    actualDaysOfMonthMap[v] = true
+                }
+            }
+        }
+        // days of week of specific week in the month
+        //  offset : (7 - day_of_week_of_1st_day_of_month)
+        //  target : (7 * week_of_month) + (offset + day_of_week) % 7 + 1
+        for v, _ := range cronexpr.specificWeekDaysOfWeek {
+            v := 1 + 7*(v/7) + (offset+v)%7
+            if v <= lastDayOfMonth {
+                actualDaysOfMonthMap[v] = true
+            }
+        }
+        // Last days of week of the month
+        lastWeekOrigin := timeOrigin.AddDate(0, 1, -7)
+        offset = 7 - int(lastWeekOrigin.Weekday())
+        for v, _ := range cronexpr.lastWeekDaysOfWeek {
+            v := lastWeekOrigin.Day() + (offset+v)%7
+            if v <= lastDayOfMonth {
+                actualDaysOfMonthMap[v] = true
+            }
+        }
+    }
+
+    return toList(actualDaysOfMonthMap)
+}
+
+/******************************************************************************/
+
+func (cronexpr *CronExpression) nextDayOfMonth(t time.Time) time.Time {
+    // Find index at which item in list is greater or equal to
+    // candidate day of month
+    i := sort.SearchInts(cronexpr.actualDaysOfMonthList, t.Day()+1)
+    if i == len(cronexpr.actualDaysOfMonthList) {
+        return cronexpr.nextMonth(t)
+    }
+
+    return time.Date(
+        t.Year(),
+        t.Month(),
+        cronexpr.actualDaysOfMonthList[i],
+        cronexpr.hourList[0],
+        cronexpr.minuteList[0],
+        cronexpr.secondList[0],
+        0,
+        t.Location())
+}
+
+/******************************************************************************/
+
+func (cronexpr *CronExpression) nextHour(t time.Time) time.Time {
+    // Find index at which item in list is greater or equal to
+    // candidate hour
+    i := sort.SearchInts(cronexpr.hourList, t.Hour()+1)
+    if i == len(cronexpr.hourList) {
+        return cronexpr.nextDayOfMonth(t)
+    }
+
+    return time.Date(
+        t.Year(),
+        t.Month(),
+        t.Day(),
+        cronexpr.hourList[i],
+        cronexpr.minuteList[0],
+        cronexpr.secondList[0],
+        0,
+        t.Location())
+}
+
+/******************************************************************************/
+
+func (cronexpr *CronExpression) nextMinute(t time.Time) time.Time {
+    // Find index at which item in list is greater or equal to
+    // candidate minute
+    i := sort.SearchInts(cronexpr.minuteList, t.Minute()+1)
+    if i == len(cronexpr.minuteList) {
+        return cronexpr.nextHour(t)
+    }
+
+    return time.Date(
+        t.Year(),
+        t.Month(),
+        t.Day(),
+        t.Hour(),
+        cronexpr.minuteList[i],
+        cronexpr.secondList[0],
+        0,
+        t.Location())
+}
+
+/******************************************************************************/
+
+func (cronexpr *CronExpression) nextSecond(t time.Time) time.Time {
+    // nextSecond() assumes all other fields are exactly matched
+    // to the cron expression
+
+    // Find index at which item in list is greater or equal to
+    // candidate second
+    i := sort.SearchInts(cronexpr.secondList, t.Second()+1)
+    if i == len(cronexpr.secondList) {
+        return cronexpr.nextMinute(t)
+    }
+
+    return time.Date(
+        t.Year(),
+        t.Month(),
+        t.Day(),
+        t.Hour(),
+        t.Minute(),
+        cronexpr.secondList[i],
+        0,
+        t.Location())
+}
+
+/******************************************************************************/
+
+var cronNormalizer = strings.NewReplacer(
+    // Order is important!
+    "@yearly", "0 0 0 1 1 * *",
+    "@annually", "0 0 0 1 1 * *",
+    "@monthly", "0 0 0 1 * * *",
+    "@weekly", "0 0 0 * * 0 *",
+    "@daily", "0 0 0 * * * *",
+    "@hourly", "0 0 * * * * *",
+    "january", "1",
+    "february", "2",
+    "march", "3",
+    "april", "4",
+    "may", "5",
+    "june", "6",
+    "july", "7",
+    "august", "8",
+    "september", "9",
+    "october", "0",
+    "november", "1",
+    "december", "2",
+    "sunday", "0",
+    "monday", "1",
+    "tuesday", "2",
+    "wednesday", "3",
+    "thursday", "4",
+    "friday", "5",
+    "saturday", "6",
+    "jan", "1",
+    "feb", "2",
+    "mar", "3",
+    "apr", "4",
+    "jun", "6",
+    "jul", "7",
+    "aug", "8",
+    "sep", "9",
+    "oct", "0",
+    "nov", "1",
+    "dec", "2",
+    "sun", "0",
+    "mon", "1",
+    "tue", "2",
+    "wed", "3",
+    "thu", "4",
+    "fri", "5",
+    "sat", "6",
+    "?", "*")
+
+func cronNormalize(cronLine string) string {
+    cronLine = strings.TrimSpace(cronLine)
+    cronLine = strings.ToLower(cronLine)
+    cronLine = cronNormalizer.Replace(cronLine)
+    return cronLine
+}
+
+/******************************************************************************/
+
+func (cronexpr *CronExpression) dayofweekFieldParse(cronField string) error {
+    // Defaults
+    cronexpr.daysOfWeekRestricted = true
+    cronexpr.lastWeekDaysOfWeek = make(map[int]bool)
+    cronexpr.daysOfWeek = make(map[int]bool)
+
+    // "You can also mix all of the above, as in: 1-5,10,12,20-30/5"
+    cronList := strings.Split(cronField, ",")
+    for _, s := range cronList {
+        // "/"
+        step, s := extractInterval(s)
+        // "*"
+        if s == "*" {
+            cronexpr.daysOfWeekRestricted = (step > 1)
+            populateMany(cronexpr.daysOfWeek, 0, 6, step)
+            continue
+        }
+        // "-"
+        // week day interval for all weeks
+        i := strings.Index(s, "-")
+        if i >= 0 {
+            min := atoi(s[:i]) % 7
+            max := atoi(s[i+1:]) % 7
+            populateMany(cronexpr.daysOfWeek, min, max, step)
+            continue
+        }
+        // single value
+        // "l": week day for last week
+        i = strings.Index(s, "l")
+        if i >= 0 {
+            populateOne(cronexpr.lastWeekDaysOfWeek, atoi(s[:i])%7)
+            continue
+        }
+        // "#": week day for specific week
+        i = strings.Index(s, "#")
+        if i >= 0 {
+            // v#w
+            v := atoi(s[:i]) % 7
+            w := atoi(s[i+1:])
+            // v domain = [0,7]
+            // w domain = [1,5]
+            populateOne(cronexpr.specificWeekDaysOfWeek, (w-1)*7+(v%7))
+            continue
+        }
+        // week day interval for all weeks
+        if step > 0 {
+            v := atoi(s) % 7
+            populateMany(cronexpr.daysOfWeek, v, 6, step)
+            continue
+        }
+        // single week day for all weeks
+        v := atoi(s) % 7
+        populateOne(cronexpr.daysOfWeek, v)
+    }
+
+    return nil
+}
+
+/******************************************************************************/
+
+func (cronexpr *CronExpression) dayofmonthFieldParse(cronField string) error {
+    // Defaults
+    cronexpr.daysOfMonthRestricted = true
+    cronexpr.lastDayOfMonth = false
+
+    cronexpr.daysOfMonth = make(map[int]bool)     // days of month map
+    cronexpr.workdaysOfMonth = make(map[int]bool) // work day of month map
+
+    // "You can also mix all of the above, as in: 1-5,10,12,20-30/5"
+    cronList := strings.Split(cronField, ",")
+    for _, s := range cronList {
+        // "/"
+        step, s := extractInterval(s)
+        // "*"
+        if s == "*" {
+            cronexpr.daysOfMonthRestricted = (step > 1)
+            populateMany(cronexpr.daysOfMonth, 1, 31, step)
+            continue
+        }
+        // "-"
+        i := strings.Index(s, "-")
+        if i >= 0 {
+            populateMany(cronexpr.daysOfMonth, atoi(s[:i]), atoi(s[i+1:]), step)
+            continue
+        }
+        // single value
+        // "l": last day of month
+        if s == "l" {
+            cronexpr.lastDayOfMonth = true
+            continue
+        }
+        // "w": week day
+        i = strings.Index(s, "w")
+        if i >= 0 {
+            populateOne(cronexpr.workdaysOfMonth, atoi(s[:i]))
+            continue
+        }
+        // single value with interval
+        if step > 0 {
+            populateMany(cronexpr.daysOfMonth, atoi(s), 31, step)
+            continue
+        }
+        // single value
+        populateOne(cronexpr.daysOfMonth, atoi(s))
+    }
+
+    return nil
+}
+
+/******************************************************************************/
+
+func genericFieldParse(cronField string, min, max int) []int {
+    // Defaults
+    values := make(map[int]bool)
+
+    // "You can also mix all of the above, as in: 1-5,10,12,20-30/5"
+    cronList := strings.Split(cronField, ",")
+    for _, s := range cronList {
+        // "/"
+        step, s := extractInterval(s)
+        // "*"
+        if s == "*" {
+            populateMany(values, min, max, step)
+            continue
+        }
+        // "-"
+        i := strings.Index(s, "-")
+        if i >= 0 {
+            populateMany(values, atoi(s[:i]), atoi(s[i+1:]), step)
+            continue
+        }
+        // single value with interval
+        if step > 0 {
+            populateMany(values, atoi(s), max, step)
+            continue
+        }
+        // single value
+        populateOne(values, atoi(s))
+    }
+
+    return toList(values)
+}
+
+/******************************************************************************/
+
+// Local helpers
+
+func extractInterval(s string) (int, string) {
+    step := 0
+    i := strings.Index(s, "/")
+    if i >= 0 {
+        step = atoi(s[i+1:])
+        s = s[:i]
+    }
+    return step, s
+}
+
+func atoi(s string) int {
+    v, err := strconv.Atoi(s)
+    if err != nil {
+        panic(err)
+    }
+    return v
+}
+
+func populateOne(values map[int]bool, v int) {
+    values[v] = true
+}
+
+func populateMany(values map[int]bool, min, max, step int) {
+    if step == 0 {
+        step = 1
+    }
+    for i := min; i <= max; i += step {
+        values[i] = true
+    }
+}
+
+func toList(set map[int]bool) []int {
+    list := make([]int, len(set))
+    i := 0
+    for k, _ := range set {
+        list[i] = k
+        i += 1
+    }
+    sort.Ints(list)
+    return list
+}