README
¶
Go Schedule
A schedule utility to generate all the dates.
Installation
go get github.com/io-da/schedule
Overview
Introduction
This library is intended to be used as an utility for generating time.Time structs.
It should provide an alternative to Linux's Cron and Crontab with some extra spice.
This library purposely does not implement the actual job handling/execution.
Clean codebase. No reflection, no closures.
Getting Started
Schedule
Schedule is the struct used to represent a set of retrievable time.Time structs.
Optionally it can also contain a CronExpression that will only start producing time.Time structs after the scheduled ones.
Schedules can be initialized in 2 ways: schedule.At(at ...time.Time) or schedule.In(in ...time.Duration).
schedule.At creates a Schedule that returns the provided time.Time structs.
schedule.In creates a Schedule that returns time.Now() plus the provided time.Duration values.
schedule.As creates a Schedule that returns the dates generated by the provided CronExpression.
The time.Time structs can be retrieved by executing the function sch.Following().
Moving the Schedule state forward is achieved by executing the function sch.Next().
Optionally it is also possible to provide a CronExpression to a Schedule (sch.AddCron(crn *CronExpression)).
The CronExpression will only start to be used after the schedules times.
CronExpression
CronExpression struct represents a full crontab expression.
An expression is initialized using the function schedule.Cron().
This expression is defined by using a set of functions designed for readability.
The CronExpression does not generate times it self. For that we need a CronInstance.
At 00:00 on day-of-month 29 and on Sunday in February. (0 0 29 2 0):
Cron().
OnMonths(time.February).
OnDays(29).
OnWeekdays(time.Sunday)
IteratorExpression
Iterator expressions are any type that implements the IteratorExpression interface.
These are used to represent sets of values.
type IteratorExpression interface {
Next(from int, inc bool) (int, bool)
Contains(val int) bool
}
The library provides 2 different ones.
BetweenExpression:
type BetweenExpression struct {
x int
y int
step int
}
This expression also allows configuration of it's stepping value using Every(s int).
ListExpression:
type ListExpression struct {
values []int
}
(Between) Every 2 hours: Cron().OnHours(BetweenHours(0,22).Every(2))
(List) Specifically at 0 and 12 hours: Cron().OnHours(ListHours(0,12))
CronInstance
To start generating time.Time structs, we just need to create a CronInstance from the CronExpression crn.NewInstance(from time.Time).
It is required to provide a from time.Time for the CronInstance to be able to identify its following time.Time.
The CronInstance exposes only 2 functions.
Next() error
Following() time.Time
Next() is used to determine the next following time.Time. Every execution advances it's internal state.
Following() is used to retrieve the determined time.Time. It can be retrieved without any consequence.
Putting it together
import (
"github.com/io-da/schedule"
)
func main() {
// instantiate a schedule that produces a time.Time one hour in the future
sch := schedule.In(time.Hour)
// setup a cron to start producing time.Time every hour thereafter
sch.AddCron(schedule.Cron().EveryHour())
for {
// check if the schedule/cron expired
if err := sch.Next(); err == nil {
// and potentially handle the error
hypotheticalLogger.error(err)
break
}
// retrieve the determined time.Time
at := sch.Following()
// and handle it
hypotheticalTaskManager.Add(hypotheticalTask, at)
}
}
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
License
Documentation
¶
Index ¶
- Constants
- type AttunedMonth
- func (my *AttunedMonth) Contains(d int) bool
- func (my *AttunedMonth) IsMonthLastDay(d int) bool
- func (my *AttunedMonth) Month() time.Month
- func (my *AttunedMonth) MonthLastDay() int
- func (my *AttunedMonth) UpdateMonth(mon int)
- func (my *AttunedMonth) UpdateMonthYear(mon int, y int)
- func (my *AttunedMonth) WeekDay(d int) time.Weekday
- func (my *AttunedMonth) Year() int
- type BetweenExpression
- func Between(x int, y int) *BetweenExpression
- func BetweenDays(x int, y int) *BetweenExpression
- func BetweenHours(x int, y int) *BetweenExpression
- func BetweenMilliseconds(x int, y int) *BetweenExpression
- func BetweenMinutes(x int, y int) *BetweenExpression
- func BetweenMonths(x time.Month, y time.Month) *BetweenExpression
- func BetweenSeconds(x int, y int) *BetweenExpression
- func BetweenWeekdays(x time.Weekday, y time.Weekday) *BetweenExpression
- func BetweenYears(x int, y int) *BetweenExpression
- type CronExpression
- func (crn *CronExpression) EveryDay() *CronExpression
- func (crn *CronExpression) EveryHour() *CronExpression
- func (crn *CronExpression) EveryMillisecond() *CronExpression
- func (crn *CronExpression) EveryMinute() *CronExpression
- func (crn *CronExpression) EveryMonth() *CronExpression
- func (crn *CronExpression) EverySecond() *CronExpression
- func (crn *CronExpression) NewInstance(from time.Time) *CronInstance
- func (crn *CronExpression) OnDays(exp Expression) *CronExpression
- func (crn *CronExpression) OnHours(exp Expression) *CronExpression
- func (crn *CronExpression) OnMilliseconds(exp Expression) *CronExpression
- func (crn *CronExpression) OnMinutes(exp Expression) *CronExpression
- func (crn *CronExpression) OnMonths(exp Expression) *CronExpression
- func (crn *CronExpression) OnSeconds(exp Expression) *CronExpression
- func (crn *CronExpression) OnWeekdays(exp Expression) *CronExpression
- func (crn *CronExpression) OnYears(exp Expression) *CronExpression
- type CronInstance
- type ErrorOutdated
- type ErrorOutdatedInvalidCron
- type Expression
- type IteratorExpression
- type ListExpression
- func List(values []int) *ListExpression
- func ListDays(values ...int) *ListExpression
- func ListHours(values ...int) *ListExpression
- func ListMilliseconds(values ...int) *ListExpression
- func ListMinutes(values ...int) *ListExpression
- func ListMonths(values ...time.Month) *ListExpression
- func ListSeconds(values ...int) *ListExpression
- func ListWeekdays(values ...time.Weekday) *ListExpression
- func ListYears(values ...int) *ListExpression
- type Schedule
Constants ¶
const CronOutdatedInvalidError = ErrorOutdatedInvalidCron("schedule: outdated or invalid CronExpression")
CronOutdatedInvalidError is a constant equivalent of the ErrorOutdatedInvalidCron error.
const OutdatedError = ErrorOutdated("schedule: outdated or invalid Schedule")
OutdatedError is a constant equivalent of the ErrorOutdated error.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AttunedMonth ¶
type AttunedMonth struct {
// contains filtered or unexported fields
}
AttunedMonth is an upgrade to the regular time.Month attuned to the year provided. It is self aware of it's last day and week days.
func NewAttunedMonth ¶
func NewAttunedMonth(mon int, y int) *AttunedMonth
NewAttunedMonth returns a reference to a new AttunedMonth.
func (*AttunedMonth) Contains ¶
func (my *AttunedMonth) Contains(d int) bool
Contains verifies if this month contains the provided day.
func (*AttunedMonth) IsMonthLastDay ¶
func (my *AttunedMonth) IsMonthLastDay(d int) bool
IsMonthLastDay verifies if the provided day is the last day of this month.
func (*AttunedMonth) Month ¶
func (my *AttunedMonth) Month() time.Month
Month returns the time.Month type representation of the month.
func (*AttunedMonth) MonthLastDay ¶
func (my *AttunedMonth) MonthLastDay() int
MonthLastDay returns the last day of this month
func (*AttunedMonth) UpdateMonth ¶
func (my *AttunedMonth) UpdateMonth(mon int)
UpdateMonth updates the month and recalculates the necessary components.
func (*AttunedMonth) UpdateMonthYear ¶
func (my *AttunedMonth) UpdateMonthYear(mon int, y int)
UpdateMonthYear updates both month and year and recalculates the necessary components.
func (*AttunedMonth) WeekDay ¶
func (my *AttunedMonth) WeekDay(d int) time.Weekday
WeekDay returns the time.Weekday type representation of the provided day.
func (*AttunedMonth) Year ¶
func (my *AttunedMonth) Year() int
Year returns the int value of the year.
type BetweenExpression ¶
type BetweenExpression struct {
// contains filtered or unexported fields
}
BetweenExpression is the struct used to create cron between expressions.
func Between ¶
func Between(x int, y int) *BetweenExpression
Between is an expression that generates integers between the provided parameters (*inclusive*).
func BetweenDays ¶
func BetweenDays(x int, y int) *BetweenExpression
BetweenDays uses the regular between logic, ensuring valid day parameters.
func BetweenHours ¶
func BetweenHours(x int, y int) *BetweenExpression
BetweenHours uses the regular between logic, ensuring valid hour parameters.
func BetweenMilliseconds ¶
func BetweenMilliseconds(x int, y int) *BetweenExpression
BetweenMilliseconds uses the regular between logic, ensuring valid millisecond parameters.
func BetweenMinutes ¶
func BetweenMinutes(x int, y int) *BetweenExpression
BetweenMinutes uses the regular between logic, ensuring valid minute parameters.
func BetweenMonths ¶
func BetweenMonths(x time.Month, y time.Month) *BetweenExpression
BetweenMonths uses the regular between logic, ensuring valid time.Month parameters.
func BetweenSeconds ¶
func BetweenSeconds(x int, y int) *BetweenExpression
BetweenSeconds uses the regular between logic, ensuring valid second parameters.
func BetweenWeekdays ¶
func BetweenWeekdays(x time.Weekday, y time.Weekday) *BetweenExpression
BetweenWeekdays uses the regular between logic, ensuring valid time.Weekday parameters.
func BetweenYears ¶
func BetweenYears(x int, y int) *BetweenExpression
BetweenYears uses the regular between logic, ensuring valid year parameters.
func (*BetweenExpression) Contains ¶
func (exp *BetweenExpression) Contains(val int) bool
Contains verifies if the provided value belongs to this expression.
func (*BetweenExpression) Every ¶
func (exp *BetweenExpression) Every(s int) *BetweenExpression
Every allows optional specification of the stepping used for the between logic. It's important to understand the behavior of the expression when step > 1. It may produce some unexpected values. Example: Between(0,10).Every(3)
- Next(-1, true || false) = 0
- Next(0, true) = 0
- Next(0, false) = 3
- Next(1, true || false) = 3
- Next(3, false) = 6
- Next(6, false) = 9
- Next(9, false) = 10
- Next(10, true || false) = 10
func (*BetweenExpression) Next ¶
func (exp *BetweenExpression) Next(from int, inc bool) (int, bool)
Next allows retrieval of the next value from this expression. Expressions are stateless, the determination of their next value is based on input. Given a valid expression value, the parameter inc is used to specify if it should be included in the output. Given the last value of the expression or above, the inc parameter is ignored. It returns the next value according to provided parameters and a boolean indicating if it is the last value.
type CronExpression ¶
type CronExpression struct {
// contains filtered or unexported fields
}
CronExpression is used to represent the complete cron expression. It is used to create new CronInstances.
func Cron ¶
func Cron() *CronExpression
Cron creates and returns a reference to a new CronExpression.
func (*CronExpression) EveryDay ¶
func (crn *CronExpression) EveryDay() *CronExpression
EveryDay sets this expression to return a date for every day.
func (*CronExpression) EveryHour ¶
func (crn *CronExpression) EveryHour() *CronExpression
EveryHour sets this expression to return a date for every hour.
func (*CronExpression) EveryMillisecond ¶
func (crn *CronExpression) EveryMillisecond() *CronExpression
EveryMillisecond sets this expression to return a date for every millisecond.
func (*CronExpression) EveryMinute ¶
func (crn *CronExpression) EveryMinute() *CronExpression
EveryMinute sets this expression to return a date for every minute.
func (*CronExpression) EveryMonth ¶
func (crn *CronExpression) EveryMonth() *CronExpression
EveryMonth sets this expression to return a date for every month.
func (*CronExpression) EverySecond ¶
func (crn *CronExpression) EverySecond() *CronExpression
EverySecond sets this expression to return a date for every second.
func (*CronExpression) NewInstance ¶
func (crn *CronExpression) NewInstance(from time.Time) *CronInstance
NewInstance creates and returns a reference to a new CronInstance for the referenced CronExpression.
func (*CronExpression) OnDays ¶
func (crn *CronExpression) OnDays(exp Expression) *CronExpression
OnDays sets this expression to return a date on the provided days.
func (*CronExpression) OnHours ¶
func (crn *CronExpression) OnHours(exp Expression) *CronExpression
OnHours sets this expression to return a date on the provided hours.
func (*CronExpression) OnMilliseconds ¶
func (crn *CronExpression) OnMilliseconds(exp Expression) *CronExpression
OnMilliseconds sets this expression to return a date on the provided millisecond.
func (*CronExpression) OnMinutes ¶
func (crn *CronExpression) OnMinutes(exp Expression) *CronExpression
OnMinutes sets this expression to return a date on the provided minutes.
func (*CronExpression) OnMonths ¶
func (crn *CronExpression) OnMonths(exp Expression) *CronExpression
OnMonths sets this expression to return a date on the provided months.
func (*CronExpression) OnSeconds ¶
func (crn *CronExpression) OnSeconds(exp Expression) *CronExpression
OnSeconds sets this expression to return a date on the provided seconds.
func (*CronExpression) OnWeekdays ¶
func (crn *CronExpression) OnWeekdays(exp Expression) *CronExpression
OnWeekdays sets this expression to return a date on the provided weekdays.
func (*CronExpression) OnYears ¶
func (crn *CronExpression) OnYears(exp Expression) *CronExpression
OnYears sets this expression to return a date on the provided years.
type CronInstance ¶
type CronInstance struct {
// contains filtered or unexported fields
}
CronInstance is created from CronExpression's and is used to hold state and determine next cron date according to it's expression.
func (*CronInstance) Following ¶
func (crnI *CronInstance) Following() time.Time
Following returns the following valid cron date determined by the Next function without modifying its state.
func (*CronInstance) Next ¶
func (crnI *CronInstance) Next() error
Next uses it's following date to determine the next valid cron date according to it's expression. Each subsequent execution advances the instance's following date.
type ErrorOutdated ¶
type ErrorOutdated string
ErrorOutdated is used to represent a schedule that became outdated.
func (ErrorOutdated) Error ¶
func (e ErrorOutdated) Error() string
Error produces a string message of this error.
type ErrorOutdatedInvalidCron ¶
type ErrorOutdatedInvalidCron string
ErrorOutdatedInvalidCron is used to represent a cron that has entered an invalid state or is outdated.
func (ErrorOutdatedInvalidCron) Error ¶
func (e ErrorOutdatedInvalidCron) Error() string
Error produces a string message of this error.
type Expression ¶
type Expression interface {
}
Expression is used as an empty interface, for readability purposes.
type IteratorExpression ¶
IteratorExpression is used by expressions that represent a sequential set of values.
type ListExpression ¶
type ListExpression struct {
// contains filtered or unexported fields
}
ListExpression is the struct used to create cron list expressions.
func List ¶
func List(values []int) *ListExpression
List is an expression used to iterate the provided list of int parameters (*inclusive*).
func ListDays ¶
func ListDays(values ...int) *ListExpression
ListDays uses the regular list logic, ensuring valid day parameters.
func ListHours ¶
func ListHours(values ...int) *ListExpression
ListHours uses the regular list logic, ensuring valid hour parameters.
func ListMilliseconds ¶
func ListMilliseconds(values ...int) *ListExpression
ListMilliseconds uses the regular list logic, ensuring valid millisecond parameters.
func ListMinutes ¶
func ListMinutes(values ...int) *ListExpression
ListMinutes uses the regular list logic, ensuring valid minute parameters.
func ListMonths ¶
func ListMonths(values ...time.Month) *ListExpression
ListMonths uses the regular list logic, ensuring valid time.Month parameters.
func ListSeconds ¶
func ListSeconds(values ...int) *ListExpression
ListSeconds uses the regular list logic, ensuring valid second parameters.
func ListWeekdays ¶
func ListWeekdays(values ...time.Weekday) *ListExpression
ListWeekdays uses the regular list logic, ensuring valid time.Weekday parameters.
func ListYears ¶
func ListYears(values ...int) *ListExpression
ListYears uses the regular list logic, ensuring valid year parameters.
func (*ListExpression) Contains ¶
func (exp *ListExpression) Contains(val int) bool
Contains verifies if the provided value belongs to this expression
func (*ListExpression) Next ¶
func (exp *ListExpression) Next(from int, inc bool) (int, bool)
Next allows retrieval of the next value from this expression. Expressions are stateless, the determination of their next value is based on input. Given a valid expression value, the parameter inc is used to specify if it should be included in the output. Given the last value of the expression or above, the inc parameter is ignored. It returns the next value according to provided parameters and a boolean indicating if it is the last value.
type Schedule ¶
type Schedule struct {
// contains filtered or unexported fields
}
Schedule is the struct used to represent a set of retrievable time.Time structs.
func As ¶ added in v1.1.0
func As(crn *CronExpression) *Schedule
As creates a new schedule that produces dates based on the provided CronExpression. Example: As(Cron().EveryDay()):
date = 00:00:00 of the following day; ...
func In ¶
In creates a new schedule that produces dates based on provided durations. The durations are added sequentially. Example: In(time.Second, time.Minute):
date = time.Now().Add(time.Second); date = date.Add(time.Minute).
func (*Schedule) AddCron ¶ added in v1.1.0
func (sch *Schedule) AddCron(crn *CronExpression)
AddCron is used to setup a CronExpression that starts operating after the scheduled times pass. Example: In(time.Hour * 24 * 7).AddCron(Cron().EveryDay()):
date = time.Now().Add(time.Hour * 24 * 7); date = 00:00:00 of the following day; ...
Source Files