cron

README

Joe Bot - Cron Module

Emiting events on recurring schedules. https://github.com/go-joe/joe

---

This repository contains a module for the Joe Bot library.

Getting Started

This library is packaged as Go module. You can get it via:

go get github.com/go-joe/cron

Example usage

This module allows you to run arbitrary functions or emit events on a schedule using a cron expressions or simply an interval expressed as time.Duration.

package main

import (
	"time"
	"github.com/go-joe/joe"
	"github.com/go-joe/cron"
)

type MyEvent struct {}

func main() {
	b := joe.New("example-bot",
		// emit a cron.Event once every day at midnight
		cron.ScheduleEvent("0 0 * * *"),
		
		// emit your own custom event every day at 09:00
		cron.ScheduleEvent("0 9 * * *", MyEvent{}), 
		
		// emit your own custom event every day at 09:00:30
		cron.ScheduleEvent("30 0 9 * * *", MyEvent{}),

		// cron expressions can be hard to read and might be overkill
		cron.ScheduleEventEvery(time.Hour, MyEvent{}), 
		
		// sometimes its easier to use a function
		cron.ScheduleFunc("0 9 * * *", func() { /* TODO */ }), 
		
		// functions can also be scheduled on simple intervals
		cron.ScheduleFuncEvery(5*time.Minute, func() { /* TODO */ }),
    )
	
	err := b.Run()
	if err != nil {
		b.Logger.Fatal(err.Error())
	}
}

Built With

• robfig/cron - A cron library for go
• zap - Blazing fast, structured, leveled logging in Go
• testify - A simple unit test library

Contributing

If you want to hack on this repository, please read the short CONTRIBUTING.md guide first.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Friedrich Große - Initial work - fgrosse
• Julius Bachnick - Update cron library to v3 - juliusbachnick

See also the list of contributors who participated in this project.

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

Documentation

Overview

Package cron implements cron jobs for the Joe bot library. https://github.com/go-joe/joe

Index

• Variables
• type Event
• type Job
  • func ScheduleEvent(schedule string, events ...interface{}) *Job
  • func ScheduleEventEvery(schedule time.Duration, events ...interface{}) *Job
  • func ScheduleFunc(schedule string, fun func()) *Job
  • func ScheduleFuncEvery(schedule time.Duration, fun func()) *Job
  • func (j *Job) Apply(conf *joe.Config) error
  • func (j *Job) Close() error
  • func (j *Job) Start(logger *zap.Logger, events joe.EventEmitter) error

Variables

var Parser = cron.NewParser(
	cron.SecondOptional | cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow | cron.Descriptor,
)

Parser is the default cron.Parser which is configured to accept standard cron schedules with optional seconds.

Types

type Event

type Event struct{}

Event is the event that the ScheduleEvent(…) type functions emit if no custom event was passed as argument. It can be useful to implement simple jobs that do not require any context but just a schedule that triggers them at an interval.

type Job

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

A Job is a joe.Module that runs a single cron job on a given interval.

func ScheduleEvent

func ScheduleEvent(schedule string, events ...interface{}) *Job

ScheduleEvent creates a joe.Module that emits one or many events on a given cron schedule (e.g. "0 0 * * *"). If the passed schedule is not a valid cron schedule as accepted by the package level Parser, the corresponding error will be returned when the bot is started.

You can execute this function with only a schedule but no events. In this case the job will emit an instance of the cron.Event type that is defined in this package. Otherwise all passed events are emitted on the schedule.

func ScheduleEventEvery

func ScheduleEventEvery(schedule time.Duration, events ...interface{}) *Job

ScheduleEventEvery creates a joe.Module that emits one or many events on a given interval (e.g. every hour). The minimum duration is one second and any smaller durations will be rounded up to that.

You can execute this function with only a schedule but no events. In this case the job will emit an instance of the cron.Event type that is defined in this package. Otherwise all passed events are emitted on the schedule.

func ScheduleFunc

func ScheduleFunc(schedule string, fun func()) *Job

ScheduleFunc creates a joe.Module that runs the given function on a given cron schedule (e.g. "0 0 * * *"). Optionally, the cron schedule can also contain seconds, i.e. "30 0 0 * * *".

If the passed schedule is not a valid cron schedule as accepted by the package level Parser, the corresponding error will be returned when the bot is started.

func ScheduleFuncEvery

func ScheduleFuncEvery(schedule time.Duration, fun func()) *Job

ScheduleFuncEvery creates a joe.Module that runs the given function on a given interval (e.g. every hour). The minimum duration is one second and any smaller durations will be rounded up to that.

func (*Job) Apply

func (j *Job) Apply(conf *joe.Config) error

Apply implements joe.Module by starting a new cron job that may use the event emitter from the configuration (if it actually emits events). Jobs that only run functions will only require a logger.

func (*Job) Close

func (j *Job) Close() error

Close stops the cron job.

func (*Job) Start

func (j *Job) Start(logger *zap.Logger, events joe.EventEmitter) error

Start starts the cron job. If you are using the job as joe.Module there is no need to start the job explicitly. This function is useful if you want to manage jobs yourself if you do not pass them to the bot as joe.Module.

If the job does not actually emit events, the passed event emitter will not be used and can be nil.