cron

Documentation

Overview

Package cron parses standard cron expressions and resolves them against the calendar to answer "when is the next/previous occurrence" and "how long until/since it".

series, err := cron.NewCronSeries("*/15 * * * *") // every 15 minutes
if err != nil {
    return err
}
for {
    wait, err := series.UntilNext(time.Now())
    if err != nil {
        return err
    }
    time.Sleep(wait)
    doSomething()
}

CronSeries is the entry point: parse an expression with NewCronSeries, then query it with Next/Prev (absolute time.Time) or UntilNext/SincePrev (time.Duration, as used above). CronSeries is stateless: every method is a pure function of its argument, so the same value can be shared across goroutines and queried repeatedly without synchronization.

Expression syntax

A standard expression has 5 fields: minute, hour, day-of-month, month, day-of-week. Each field accepts a wildcard ("*"), a single value, a range ("1-5"), a step ("*/5", "1-30/5"), or a comma-separated list of any of those. Month and day-of-week fields also accept the standard three-letter names ("jan"-"dec", "sun"-"sat"), case-insensitively.

• A 6-field expression prepends seconds ("second minute hour day-of-month month day-of-week"), raising the schedule's resolution from minutes to seconds.
• A 7-field expression additionally appends a year field.
• This field order matches robfig/cron, the de facto standard Go cron library; it differs from croniter, which appends seconds and year at the end instead of prepending seconds.
• When both day-of-month and day-of-week are restricted (neither is "*"), standard cron matches a day by their union: it fires when either field matches, not only when both do. This is the same rule vixie cron and its descendants use; see man 5 crontab.
• A leading "@" alias expands to a fixed expression before parsing: @yearly/@annually ("0 0 1 1 *"), @monthly ("0 0 1 * *"), @weekly ("0 0 * * 0"), @daily/@midnight ("0 0 * * *"), @hourly ("0 * * * *").

Errors

NewCronSeries wraps ErrInvalidExpr for any parse failure; check with errors.Is. UntilNext and SincePrev wrap ErrNoMatch when no occurrence exists within the search window (for example an impossible calendar date such as February 31st). Next and Prev have no error return: they signal the same condition with the zero time.Time, checkable with IsZero.

Index

• Variables
• func IsValid(expr string) bool
• type CronSeries
  • func NewCronSeries(expr string) (*CronSeries, error)
  • func (c *CronSeries) Current(after time.Time) time.Time
  • func (c *CronSeries) Match(t time.Time) bool
  • func (c *CronSeries) MatchRange(from, to time.Time) bool
  • func (c *CronSeries) Next(after time.Time) time.Time
  • func (c *CronSeries) Prev(before time.Time) time.Time
  • func (c *CronSeries) SincePrev(from time.Time) (time.Duration, error)
  • func (c *CronSeries) UntilNext(from time.Time) (time.Duration, error)

Variables

var ErrInvalidExpr = errors.New("invalid cron expression")

ErrInvalidExpr is wrapped by errors returned when a cron expression fails to parse. Use errors.Is(err, ErrInvalidExpr) to detect parse failures.

var ErrNoMatch = errors.New("no match found for expression")

ErrNoMatch is wrapped by errors returned when no scheduled time exists within the search window, for example an impossible calendar date.

Functions

func IsValid

func IsValid(expr string) bool

IsValid reports whether expr parses as a valid cron expression, without requiring a CronSeries to be kept around.

Types

type CronSeries

type CronSeries struct {
	// contains filtered or unexported fields
}

CronSeries is a parsed cron expression. It holds the set of allowed values for each field and is safe for concurrent use: all of its methods are pure functions of their argument, with no shared mutable state.

func NewCronSeries

func NewCronSeries(expr string) (*CronSeries, error)

NewCronSeries parses a cron expression and returns a CronSeries. The expression is one of the "@" aliases documented at the package level, a standard 5-field expression, a 6-field expression with a leading seconds field, or a 7-field expression additionally ending in a year field. It wraps ErrInvalidExpr if the expression is invalid.

func (*CronSeries) Current

func (c *CronSeries) Current(after time.Time) time.Time

Current is an alias for Next, kept for backwards compatibility. Prefer Next in new code.

func (*CronSeries) Match

func (c *CronSeries) Match(t time.Time) bool

Match reports whether t falls on a scheduled instant, at the schedule's own granularity: minute for a 5-field expression, second for a 6- or 7-field one (in which case seconds below that are ignored).

func (*CronSeries) MatchRange

func (c *CronSeries) MatchRange(from, to time.Time) bool

MatchRange reports whether the schedule has an occurrence within [from, to], inclusive on both ends. It returns false if to is before from.

func (*CronSeries) Next

func (c *CronSeries) Next(after time.Time) time.Time

Next returns the next scheduled time strictly after the provided time. If no match exists within the search window, it returns the zero time.Time; check with IsZero.

func (*CronSeries) Prev

func (c *CronSeries) Prev(before time.Time) time.Time

Prev returns the last scheduled time strictly before the provided time. If no match exists within the search window, it returns the zero time.Time; check with IsZero.

func (*CronSeries) SincePrev

func (c *CronSeries) SincePrev(from time.Time) (time.Duration, error)

SincePrev returns the duration since the last scheduled time before 'from', equivalent to from.Sub(Prev(from)). It wraps ErrNoMatch if no match exists within the search window.

func (*CronSeries) UntilNext

func (c *CronSeries) UntilNext(from time.Time) (time.Duration, error)

UntilNext returns the duration from 'from' until the next scheduled time, equivalent to Next(from).Sub(from). It wraps ErrNoMatch if no match exists within the search window.