gocron

package module
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 10, 2024 License: MIT Imports: 6 Imported by: 0

README

gocron

Go Reference

The gocron package provides primitives to parse a Cron expression and iterate over the activation times.

Install
go get github.com/Gilthoniel/gocron
Support

This package implements the specification found in Wikipedia and includes some advanced usages from the Quartz scheduler.

Field name Allowed values Allowed special characters
Seconds 0-59 , - * /
Minutes 0-59 , - * /
Hours 0-59 , - * /
Day of month 1-31 , - * ? / L
Month 1-12 , - * /
Day of week 0-6 or SUN-SAT , - * ? / L #
Years 1-9999 , - * /
Special characters
  • * can be used to select all values within a field (e.g. every second, every minute, ...)
  • ? can be used for no specific value in the day field or the week day field.
  • - can be used to specify an inclusive range (e.g. 1-3 means values 1, 2, and 3).
  • , can be used to list values (e.g. 1,2,3 means values 1, 2 and 3).
  • / can be used to specify an interval (e.g. 1/5 means values 1, 6, 11, 16, etc...).
  • L when used in the month field specifies the last day of the month and Saturday when used in the week day field. Using a digit before the character in the week day field specifies the nth last week day of the month (e.g. 1L for the last Monday of the month). An offset can also be used for the month field (e.g. L-2 for the second last day of the month).
  • # can be used to specify the nth week day of the month (e.g. 6#3 for the third (3) Saturday (6) of the month).

Documentation

Overview

Package gocron provides primitives to parse a Cron expression and iterate over the activation times.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrMalformedExpression  = errors.New("expression is malformed")
	ErrMalformedField       = errors.New("unexpected field value")
	ErrMultipleNotSpecified = errors.New("only one `?` is supported")
	ErrValueOutsideRange    = errors.New("values are outside the supported range")
)

Functions

This section is empty.

Types

type Iterator added in v0.1.4 

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

func (*Iterator) HasNext added in v0.1.4 

func (i *Iterator) HasNext() bool

HasNext returns true if an activation time is available. When it returns false, any call to `Next` will return a zero time.

func (*Iterator) Next added in v0.1.4 

func (i *Iterator) Next() (next time.Time)

Next returns the next activation time of the schedule, or a zero time if none is available.

type Schedule 

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

Schedule is a representation of a Cron expression.

func MustParse added in v0.1.7 

func MustParse(expression string) Schedule

MustParse returns a schedule from the Cron expression and panics in case of error.

func Parse 

func Parse(expression string) (Schedule, error)

Parse returns a schedule from the Cron expression and returns an error if the syntax is not supported or incorrect.

func (Schedule) Next 

func (s Schedule) Next(after time.Time) (next time.Time)

Next returns a time after the given argument, but never equals to it. A zero time is returned when none can be found.

Example (EveryFifteenSeconds) 
package main

import (
	"fmt"
	"time"

	"github.com/Gilthoniel/gocron"
)

func main() {
	schedule := gocron.MustParse("*/15 * * * ? *")

	next := schedule.Next(time.Date(2023, time.June, 4, 0, 0, 0, 0, time.UTC))
	fmt.Println(next)

	next = schedule.Next(next)
	fmt.Println(next)

}

Output:

2023-06-04 00:00:15 +0000 UTC
2023-06-04 00:00:30 +0000 UTC
Example (EveryLastFridayOfTheMonthAtMidnight) 
package main

import (
	"fmt"
	"time"

	"github.com/Gilthoniel/gocron"
)

func main() {
	schedule := gocron.MustParse("0 0 0 ? * 5L")

	next := schedule.Next(time.Date(2023, time.June, 4, 0, 0, 0, 0, time.UTC))
	fmt.Println(next)

	next = schedule.Next(next)
	fmt.Println(next)

}

Output:

2023-06-30 00:00:00 +0000 UTC
2023-07-28 00:00:00 +0000 UTC
Example (UsingTimezone) 
package main

import (
	"fmt"
	"time"

	"github.com/Gilthoniel/gocron"
)

func main() {
	schedule := gocron.MustParse("*/15 * * * * *")

	next := schedule.Next(time.Date(2023, time.June, 4, 0, 0, 0, 0, time.FixedZone("CEST", 120)))
	fmt.Println(next)

	next = schedule.Next(next)
	fmt.Println(next)

}

Output:

2023-06-04 00:00:15 +0002 CEST
2023-06-04 00:00:30 +0002 CEST

func (Schedule) Preceding added in v1.0.0 

func (s Schedule) Preceding(before time.Time) *Iterator

Preceding returns an iterator that will iterate over the actiation times of the Cron expression of the schedule backwards from the given time.

func (Schedule) Previous added in v0.1.7 

func (s Schedule) Previous(before time.Time) (prev time.Time)

Previous returns a time before the given argument, but never equals it. A zero time is returned when none can be found.

func (Schedule) Upcoming added in v0.1.4 

func (s Schedule) Upcoming(after time.Time) *Iterator

Upcoming returns an iterator that will iterate over the activation times of the Cron expression of the schedule forwards from the given time.

Example (EveryLastSundayOfAprilAtThreePM) 
package main

import (
	"fmt"
	"time"

	"github.com/Gilthoniel/gocron"
)

func main() {
	schedule := gocron.MustParse("0 0 15 ? 4 0L")

	iter := schedule.Upcoming(time.Date(2023, time.June, 4, 0, 0, 0, 0, time.UTC))
	for i := 0; i < 5 && iter.HasNext(); i++ {
		next := iter.Next()
		fmt.Println(next)
	}

}

Output:

2024-04-28 15:00:00 +0000 UTC
2025-04-27 15:00:00 +0000 UTC
2026-04-26 15:00:00 +0000 UTC
2027-04-25 15:00:00 +0000 UTC
2028-04-30 15:00:00 +0000 UTC
Example (EverySecondToLastDayOfEveryTwoMonths) 
package main

import (
	"fmt"
	"time"

	"github.com/Gilthoniel/gocron"
)

func main() {
	schedule := gocron.MustParse("0 0 0 L-2 */2 ?")

	iter := schedule.Upcoming(time.Date(2023, time.June, 4, 0, 0, 0, 0, time.UTC))
	for i := 0; i < 5 && iter.HasNext(); i++ {
		next := iter.Next()
		fmt.Println(next)
	}

}

Output:

2023-07-30 00:00:00 +0000 UTC
2023-09-29 00:00:00 +0000 UTC
2023-11-29 00:00:00 +0000 UTC
2024-01-30 00:00:00 +0000 UTC
2024-03-30 00:00:00 +0000 UTC
Example (EveryThirdThursdayOfEachMonth) 
package main

import (
	"fmt"
	"time"

	"github.com/Gilthoniel/gocron"
)

func main() {
	schedule := gocron.MustParse("0 0 0 ? * 4#3")

	iter := schedule.Upcoming(time.Date(2023, time.June, 4, 0, 0, 0, 0, time.UTC))
	for i := 0; i < 5 && iter.HasNext(); i++ {
		next := iter.Next()
		fmt.Println(next)
	}

}

Output:

2023-06-15 00:00:00 +0000 UTC
2023-07-20 00:00:00 +0000 UTC
2023-08-17 00:00:00 +0000 UTC
2023-09-21 00:00:00 +0000 UTC
2023-10-19 00:00:00 +0000 UTC

type TimeUnit 

type TimeUnit interface {
	// Next returns the next iteration of a schedule and `true` when valid,
	// otherwise it returns a time after `next` and `false`.
	Next(next time.Time) (time.Time, bool)

	// Previous returns the previous iteration of a schedule and `true` when
	// valid, otherwise it returns a time before `prev` and `false`.
	Previous(prev time.Time) (time.Time, bool)
}

TimeUnit represents a single part of a Cron expression.

type TimeUnitError 

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

TimeUnitError is an error returned when a time unit of a Cron expression is malformed.

func (TimeUnitError) Error 

func (e TimeUnitError) Error() string

func (TimeUnitError) Is 

func (e TimeUnitError) Is(err error) bool

func (TimeUnitError) Kind added in v0.1.4 

func (e TimeUnitError) Kind() TimeUnitKind

Kind returns the time unit kind of the error (e.g. seconds).

type TimeUnitKind 

type TimeUnitKind int
const (
	Seconds TimeUnitKind = iota
	Minutes
	Hours
	Days
	Months
	WeekDays
	Years
)

func (TimeUnitKind) String 

func (k TimeUnitKind) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.