README
¶
NOTE: Cronexpr is maintained in-tree by Supercronic, but it's forked from github.com/gorhill/cronexpr. Its license applies to the underlying code.
Golang Cron expression parser
Given a cron expression and a time stamp, you can get the next time stamp which satisfies the cron expression.
In another project, I decided to use cron expression syntax to encode scheduling information. Thus this standalone library to parse and apply time stamps to cron expressions.
The time-matching algorithm in this implementation is efficient, it avoids as much as possible to guess the next matching time stamp, a common technique seen in a number of implementations out there.
There is also a companion command-line utility to evaluate cron time expressions: https://github.com/aptible/supercronic/cronexpr/tree/master/cronexpr (which of course uses this library).
Implementation
The reference documentation for this implementation is found at https://en.wikipedia.org/wiki/Cron#CRON_expression, which I copy/pasted here (laziness!) with modifications where this implementation differs:
Field name Mandatory? Allowed values Allowed special characters
---------- ---------- -------------- --------------------------
Seconds No 0-59 * / , -
Minutes Yes 0-59 * / , -
Hours Yes 0-23 * / , -
Day of month Yes 1-31 * / , - L W
Month Yes 1-12 or JAN-DEC * / , -
Day of week Yes 0-6 or SUN-SAT * / , - L #
Year No 1970–2099 * / , -
Asterisk ( * )
The asterisk indicates that the cron expression matches for all values of the field. E.g., using an asterisk in the 4th field (month) indicates every month.
Slash ( / )
Slashes describe increments of ranges. For example 3-59/15 in the minute field indicate the third minute of the hour and every 15 minutes thereafter. The form */... is equivalent to the form "first-last/...", that is, an increment over the largest possible range of the field.
Comma ( , )
Commas are used to separate items of a list. For example, using MON,WED,FRI in the 5th field (day of week) means Mondays, Wednesdays and Fridays.
Hyphen ( - )
Hyphens define ranges. For example, 2000-2010 indicates every year between 2000 and 2010 AD, inclusive.
L
L stands for "last". When used in the day-of-week field, it allows you to specify constructs such as "the last Friday" (5L) of a given month. In the day-of-month field, it specifies the last day of the month.
W
The W character is allowed for the day-of-month field. This character is used to specify the business day (Monday-Friday) nearest the given day. As an example, if you were to specify 15W as the value for the day-of-month field, the meaning is: "the nearest business day to the 15th of the month."
So, if the 15th is a Saturday, the trigger fires on Friday the 14th. If the 15th is a Sunday, the trigger fires on Monday the 16th. If the 15th is a Tuesday, then it fires on Tuesday the 15th. However if you specify 1W as the value for day-of-month, and the 1st is a Saturday, the trigger fires on Monday the 3rd, as it does not 'jump' over the boundary of a month's days.
The W character can be specified only when the day-of-month is a single day, not a range or list of days.
The W character can also be combined with L, i.e. LW to mean "the last business day of the month."
Hash ( # )
# is allowed for the day-of-week field, and must be followed by a number between one and five. It allows you to specify constructs such as "the second Friday" of a given month.
Predefined cron expressions
(Copied from https://en.wikipedia.org/wiki/Cron#Predefined_scheduling_definitions, with text modified according to this implementation)
Entry Description Equivalent to
@annually Run once a year at midnight in the morning of January 1 0 0 0 1 1 * *
@yearly Run once a year at midnight in the morning of January 1 0 0 0 1 1 * *
@monthly Run once a month at midnight in the morning of the first of the month 0 0 0 1 * * *
@weekly Run once a week at midnight in the morning of Sunday 0 0 0 * * 0 *
@daily Run once a day at midnight 0 0 0 * * * *
@hourly Run once an hour at the beginning of the hour 0 0 * * * * *
@reboot Not supported
Other details
- If only six fields are present, a
0second field is prepended, that is,* * * * * 2013internally become0 * * * * * 2013. - If only five fields are present, a
0second field is prepended and a wildcard year field is appended, that is,* * * * Moninternally become0 * * * * Mon *. - Domain for day-of-week field is [0-7] instead of [0-6], 7 being Sunday (like 0). This to comply with http://linux.die.net/man/5/crontab#.
- As of now, the behavior of the code is undetermined if a malformed cron expression is supplied
Install
go get github.com/aptible/supercronic/cronexpr
Usage
Import the library:
import "github.com/aptible/supercronic/cronexpr"
import "time"
Simplest way:
nextTime := cronexpr.MustParse("0 0 29 2 *").Next(time.Now())
Assuming time.Now() is "2013-08-29 09:28:00", then nextTime will be "2016-02-29 00:00:00".
You can keep the returned Expression pointer around if you want to reuse it:
expr := cronexpr.MustParse("0 0 29 2 *")
nextTime := expr.Next(time.Now())
...
nextTime = expr.Next(nextTime)
Use time.IsZero() to find out whether a valid time was returned. For example,
cronexpr.MustParse("* * * * * 1980").Next(time.Now()).IsZero()
will return true, whereas
cronexpr.MustParse("* * * * * 2050").Next(time.Now()).IsZero()
will return false (as of 2013-08-29...)
You may also query for n next time stamps:
cronexpr.MustParse("0 0 29 2 *").NextN(time.Now(), 5)
which returns a slice of time.Time objects, containing the following time stamps (as of 2013-08-30):
2016-02-29 00:00:00
2020-02-29 00:00:00
2024-02-29 00:00:00
2028-02-29 00:00:00
2032-02-29 00:00:00
The time zone of time values returned by Next and NextN is always the
time zone of the time value passed as argument, unless a zero time value is
returned.
API
http://godoc.org/github.com/aptible/supercronic/cronexpr
License
License: pick the one which suits you best:
- GPL v3 see https://www.gnu.org/licenses/gpl.html
- APL v2 see http://www.apache.org/licenses/LICENSE-2.0
Documentation
¶
Overview ¶
Package cronexpr parses cron time expressions.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Expression ¶
type Expression struct {
// contains filtered or unexported fields
}
A Expression represents a specific cron time expression as defined at <https://github.com/aptible/supercronic/cronexpr#implementation>
func MustParse ¶
func MustParse(cronLine string) *Expression
MustParse returns a new Expression pointer. It expects a well-formed cron expression. If a malformed cron expression is supplied, it will `panic`. See <https://github.com/aptible/supercronic/cronexpr#implementation> for documentation about what is a well-formed cron expression from this library's point of view.
Example ¶
ExampleMustParse
t := time.Date(2013, time.August, 31, 0, 0, 0, 0, time.UTC)
nextTimes := MustParse("0 0 29 2 *").NextN(t, 5)
for i := range nextTimes {
fmt.Println(nextTimes[i].Format(time.RFC1123))
Output: Mon, 29 Feb 2016 00:00:00 UTC Sat, 29 Feb 2020 00:00:00 UTC Thu, 29 Feb 2024 00:00:00 UTC Tue, 29 Feb 2028 00:00:00 UTC Sun, 29 Feb 2032 00:00:00 UTC
func Parse ¶
func Parse(cronLine string) (*Expression, error)
func ParseStrict ¶
func ParseStrict(cronLine string) (*Expression, error)
func (*Expression) Next ¶
func (expr *Expression) Next(fromTime time.Time) time.Time
Next returns the closest time instant immediately following `fromTime` which matches the cron expression `expr`.
The `time.Location` of the returned time instant is the same as that of `fromTime`.
The zero value of time.Time is returned if no matching time instant exists or if a `fromTime` is itself a zero value.
func (*Expression) NextN ¶
NextN returns a slice of `n` closest time instants immediately following `fromTime` which match the cron expression `expr`.
The time instants in the returned slice are in chronological ascending order. The `time.Location` of the returned time instants is the same as that of `fromTime`.
A slice with len between [0-`n`] is returned, that is, if not enough existing matching time instants exist, the number of returned entries will be less than `n`.
Source Files
Directories