cronlex

Documentation

Index

• Constants
• Variables
• func ParseFunc(t *parse.Tree[Token, byte]) parse.ParseFn[Token, byte]
• func StateFunc(l lex.Lexer[Token, byte]) lex.StateFn[Token, byte]
• func Validate(t *parse.Tree[Token, byte]) error
• type Resolver
• type Schedule
  • func Parse(cron string) (Schedule, error)
  • func ProcessFunc(t *parse.Tree[Token, byte]) (Schedule, error)
• type Token
  • func (t Token) String() string

Constants

const (
	ErrEmpty       = errs.Kind("empty")
	ErrInvalid     = errs.Kind("invalid")
	ErrUnsupported = errs.Kind("unsupported")
	ErrOutOfBounds = errs.Kind("out-of-bounds")

	ErrInput     = errs.Entity("input")
	ErrNumNodes  = errs.Entity("number of nodes")
	ErrNodeType  = errs.Entity("node type")
	ErrNumEdges  = errs.Entity("number of edges")
	ErrFrequency = errs.Entity("frequency")
	ErrAlphanum  = errs.Entity("alphanumeric value")
	ErrCharacter = errs.Entity("character")

	ErrMinutes   = errs.Entity("minutes value")
	ErrHours     = errs.Entity("hours value")
	ErrMonthDays = errs.Entity("days of the month value")
	ErrMonths    = errs.Entity("month value")
	ErrWeekDays  = errs.Entity("days of the week value")
)

Variables

var (
	ErrEmptyInput          = errs.WithDomain(errDomain, ErrEmpty, ErrInput)
	ErrInvalidNumNodes     = errs.WithDomain(errDomain, ErrInvalid, ErrNumNodes)
	ErrInvalidNodeType     = errs.WithDomain(errDomain, ErrInvalid, ErrNodeType)
	ErrInvalidNumEdges     = errs.WithDomain(errDomain, ErrInvalid, ErrNumEdges)
	ErrInvalidFrequency    = errs.WithDomain(errDomain, ErrInvalid, ErrFrequency)
	ErrUnsupportedAlphanum = errs.WithDomain(errDomain, ErrUnsupported, ErrAlphanum)
	ErrOutOfBoundsAlphanum = errs.WithDomain(errDomain, ErrOutOfBounds, ErrAlphanum)
	ErrEmptyAlphanum       = errs.WithDomain(errDomain, ErrEmpty, ErrAlphanum)
	ErrInvalidAlphanum     = errs.WithDomain(errDomain, ErrInvalid, ErrAlphanum)
	ErrInvalidCharacter    = errs.WithDomain(errDomain, ErrInvalid, ErrCharacter)
)

Functions

func ParseFunc

func ParseFunc(t *parse.Tree[Token, byte]) parse.ParseFn[Token, byte]

ParseFunc is the second and middle phase of the parser, which consumes a parse.Tree scoped to Token and byte, in tandem with StateFunc, as a lexer-parser state-machine strategy.

This function continuously consumes tokens emitted by the StateFunc lexer portion of the logic, and organizes them in an abstract syntax tree. This AST is then processed into a Schedule through the ProcessFunc sequence, as a parse.Run function call.

The AST keeps a top-level node that branches into several nodes, representative of the number of top-level child nodes in the cron string ("* * * * *" means there are 5 top-level child nodes; "@weekly" means there is 1 top-level child node). If a given top-level child node contains more information than a single value (e.g. ranges, sets), then the top-level child node will be the parent to more nodes containing any Token chained to that top-level child node.

func StateFunc

func StateFunc(l lex.Lexer[Token, byte]) lex.StateFn[Token, byte]

StateFunc is the first phase of the parser, which consumes the cron string's lexemes while emitting meaningful tokens on what type of data they portray.

This function works in tandem with ParseFunc, as a parser-lexer state-machine during the parse.Run call, in Parse.

As the lexer scans through each character in the cron string, it emits tokens that are representative on the kind of data at hand, as well as the actual (zero-to-many) bytes that compose that token. E.g. a set of alphanumeric characters emit a TokenAlphaNum Token containing all of those characters, while a "*" emits a TokenStar Token, containing the "*" as value. Of course, a TokenEOF Token would hold no value.

The ParseFunc will then consume these emitted Token from a channel, and organize its AST appropriately within its own logic.

func Validate

func Validate(t *parse.Tree[Token, byte]) error

Validate scans the entire parse.Tree for inconsistencies or validation errors, returning them if raised.

Types

type Resolver

type Resolver interface {
	// Resolve returns the distance to the next occurrence, as unit values.
	Resolve(value int) int
}

Resolver describes the capabilities of a cron schedule resolver.

Implementations of Resolver should focus on calculating the difference until the next scheduled value, on a per-unit basis. This means that for each configurable schedule element (seconds, minutes, hours, etc.), an individual Resolver calculates the next occurrence for a given value.

In the context of dates and timestamps, it enables to simply resolve the next occurrence's date as a difference of the current time's units against the Resolver's configuration, and with that information to build the timestamp for the next job execution, with a time.Date call, in the schedule.Scheduler component, that would sum the current time to the values taken from the Resolver.

Implementations of Resolver must ensure that their logic functions for all date elements of Schedule, provided that the Resolver is used in that data structure.

type Schedule

type Schedule struct {
	Sec      Resolver
	Min      Resolver
	Hour     Resolver
	DayMonth Resolver
	Month    Resolver
	DayWeek  Resolver
}

Schedule describes the structure of an (extended) cron schedule, which includes all basic cron schedule elements (minutes, hours, day-of-the-month, month and weekdays), as well as support for seconds.

func Parse

func Parse(cron string) (Schedule, error)

Parse consumes the input cron string and creates a Schedule from it, also returning an error if raised.

Before parsing the string, this function validates that the cron string does not contain any illegal characters, before actually scanning and processing it.

func ProcessFunc

func ProcessFunc(t *parse.Tree[Token, byte]) (Schedule, error)

ProcessFunc is the third and last phase of the parser, which consumes a parse.Tree scoped to Token and byte, returning the new Schedule and error if raised.

This sequence will validate the nodes in the input parse.Tree, returning an error if raised. Then, depending on the configured top-level nodes, it will process the tree in the correct, supported way to derive a Schedule out of it.

type Token

type Token uint8

Token represents a unique type to mark lexemes in groups.

const (
	TokenEOF Token = iota
	TokenError
	TokenAlphaNum
	TokenStar
	TokenComma
	TokenDash
	TokenSlash
	TokenAt
	TokenSpace
)

func (Token) String

func (t Token) String() string

String implements the fmt.Stringer interface.