The cron package

The cron package implements a cron job scheduler with a lot of non-standard extensions. It allowes to run jobs periodically at fixed times, dates, frequencies and intervals.

Format

The cron expression is a string with 5, 6 or 7 fields separated by any number of whitespace like SP (0x20) or HT (0x09) from the ASCII table. Additionally, this cron package implements and supports a lot of Non-Standard Macros as listed below.

Fields

The standard crontab supports only 5 fields and cannot be scaled to seconds or years. The current implementation completes the fields as following:

• If only 5 fields are present, the seconds field with value 0 is added to the begin and the year field with value * is added to the end of the fields list.
• If only 6 fields are present, the year field with value * is added to the end of the fields list.

Field name	Required	Description	Allowed values	Allowed special characters
seconds	✕	Represents seconds.	0-59	, - * / . R
minutes	✓	Represents minutes.	0-59	, - * / . R
hours	✓	Represents hours.	0-23	, - * / . R
dom	✓	Represents days-of-month.	1-31	, - * / . R ? L W
month	✓	Represents months.	1-12 or JAN-DEC	, - * / . R
dow	✓	Represents days-of-week.	0-7 or SUN-SAT	, - * / . R ? L #
year	✕	Represents years.	1970-2099	, - * / . R

---

Note: Both, 0 and 7 value in the dow (days-of-week) field is interpreted as SUN (Sunday).

---

Note: The names in month and dow (days-of-week) fields and the special characters R, L and W are case insensitive. For example, FRI is the same as Fri or fri.

---

Special Characters

Special Character	Description
,	Commas are used to separate values in a field. For example, using MON,FRI,SUN in the dow (days-of-week) field means Monday, Friday and Sunday.
-	Hyphen defines ranges. For example, JAN-MAR in the month field means Januar, Februar and March. The current implementation supports ranges with "range-overflows" for all expression fields excepting the year field. For example, FRI-MON in the dow (days-of-week) field means Friday, Saturday, Sunday and Monday. A mix of names and numeric values in month and dow (days-of-week) fields is supported, too. For example, JAN-MAR is the same as JAN-3.
*	Asterisk is used to select all possible values within a field. For example, * in the month field means daily or every day.
/	Slash can be used to specify frequencies. For example, */10 in the seconds field means every 10 seconds. And 10/15 in the minutes field means the minutes 10, 25, 40 and 55.
.	Dot can be used to specify the current date or time value on the startup. For example, 0 . . * * * * would be updated to 0 9 15 * * * * if the cron is started-up at 09:15.
?	Question mark is used for leaving either, dom (day-of-month) or dow (day-of-week) blank. For example, 0 0 0 15 * ? * would trigger the cronjob at 15th of every month regardless of what day-of-week it is.
R	R stands for random. R can be combined with ranges, e.g. 10-30/R in the minutes field. Once generated during parsing, the random number remains constant for current field. If used in the dom (day-of-month) field without ranges, the possible values are limited to the range 1-28. To be able to use the total range set 1-31/R to the dom (day-of-month) field.
L	L stands for last. When this character is used in the dom (day-of-month) field, it specifies the last day of the month. For example, 31 January or 29 February in a leap year. In the dow (day-of-week) field, it specifies the last day of the week and simply means the SAT or 6. When this character is used in the dow (day-of-week) field and is prefixed with a number, it means the last X day of the month. For example, 1L means the last Monday of the month. MONL is the same as 1L.
W	W stands for weekday (Monday-Friday). W is used to specify the business day nearest the given day in the given month. It never jumps over the boundary of the month's days. For example, if 1W is a Saturday, the cronjob would trigger at Monday, the 3rd. The L and W special characters can also be combined in the dom (day-of-month) field as LW, which means last weekday of the month.
#	Hash allows to specifying constructs such as the second Friday of a given month. For example, 5#3 in the dow (day-of-week) field means the third Friday of every month. The value before the # has the range 0-7 or SUN-SAT. The value after the # has the range 1-5.

---

Note: Be careful with the use of ? and * special characters in the dom (day-of-month) or dow (day-of-week) fields.

---

Note: Avoid cronjobs at daylight saving times. Cronjobs can be skiped or repeated depending on whether the time moves back or jumps forward.

---

Note: It is not allowed to combine the ? with other values within a field. This special character can only be used exclusively within a field.

---

Note: It is not allowed to define the ? special character in both, dom (days-of-month) and dow (days-of-week) fields at the same time.

---

Note: If both, the dom (day-of-month) and dow (day-of-week) fields contain any values excepting the ?, the day is calculated from the best possible value of the both fields.

---

Non-Standard Macros

Macro	Description	Equivalent expression
@yearly	Run once a year at midnight of 1 January.	0 0 0 1 1 * *
@annually	The same as @yearly.	0 0 0 1 1 * *
@monthly	Run once a month at midnight of the first day of the month.	0 0 0 1 * * *
@weekly	Run once a week at midnight on Sunday.	0 0 0 * * 0 *
@daily	Run once a day at midnight.	0 0 0 * * * *
@midnight	The same as @daily.	0 0 0 * * * *
@hourly	Run once an hour at the beginning of the hour.	0 0 * * * * *
@minutely	Run once a minute at the beginning of the minute.	0 * * * * * *
@every_minute	The same as @minutely.	0 * * * * * *
@secondly	Run secondly.	* * * * * * *
@every_second	The same as @secondly.	* * * * * * *
@reboot	Run once at startup.	✕

Examples

Expression	Description
0 11 11 11 11 ? *	Run every November 11th at 11:11am.
59 59 23 31 12 ? *	Run at every turn of the year.
0 0 0 ? * LW *	Run at every last business day on the month.
0 0 0 ? * 5L *	Run at every last Friday on the month.
0 0 0 29 2 ? *	Run every February 29th on every leap year.
0 0 R * * * *	Run once a day at a random hour.
0 0 2-6/R * * * *	Run once a day at a random hour between 2:00am and 6:00am.

Code Example

import "github.com/alex-schneider/cron"

func main() {
	ctx := context.Background()

	ch, err := cron.NewJobCh(ctx, "@hourly")
	if err != nil {
		// Handle err
	}

myLoop:
	for {
		select {
		case job := <-ch:
			switch job.State {
			case int(cron.StateFound):
				go func() { /* ... */ }() // Trigger some job...
			case int(cron.StateNoMatches): // "* * * * * * 2021"
				fallthrough
			case int(cron.StateOnceExec): // "@reboot"
				break myLoop // Handle an end of a job...
			}
		case <-ctx.Done():
			/* ... */
		}
	}
}