Periodical.Recurrence (Periodical v0.2.0)

Copy Markdown View Source

A recurrence rule, written as RFC 5545 RRULE or as plain English.

Both forms describe the same thing and either is accepted:

FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,WE
every 2 weeks on Monday and Wednesday

FREQ=MONTHLY;BYDAY=-1SU
every last Sunday of the month

RRULE is the portable form a calendar application understands; English is the readable form for a configuration file. Parsing either yields the same rule, and to_rrule/1 and to_sentence/1 render it back in either.

Rules hold no process, callback, timer or implicit current time: every calculation takes an explicit reference DateTime.

The parsing, rendering and occurrence arithmetic all live in Ephemeris; this module is the boundary that keeps Periodical's own error type at its edges.

Examples

iex> {:ok, rule} = Periodical.Recurrence.parse("every last Sunday of the month")
iex> Periodical.Recurrence.next(rule, ~U[2026-01-01 09:00:00Z])
{:ok, ~U[2026-01-25 09:00:00Z]}

Summary

Types

t()

A parsed recurrence rule.

Functions

Returns the first occurrence strictly after reference.

Parses an RRULE expression or an English sentence.

Parses an expression, raising Periodical.Error when it is invalid.

Renders a rule as RFC 5545 RRULE text.

Renders a rule as an English sentence.

Types

t()

@type t() :: Ephemeris.Rule.t()

A parsed recurrence rule.

Functions

next(rule, reference)

@spec next(t(), DateTime.t()) :: {:ok, DateTime.t()} | {:error, Periodical.Error.t()}

Returns the first occurrence strictly after reference.

Strictly after, so calling it with an occurrence returns the following one rather than the same instant forever.

parse(expression)

@spec parse(String.t()) :: {:ok, t()} | {:error, Periodical.Error.t()}

Parses an RRULE expression or an English sentence.

Returns {:error, Periodical.Error.t()} rather than raising, so a rule arriving from configuration or a user can be rejected cleanly.

parse!(expression)

@spec parse!(String.t()) :: t()

Parses an expression, raising Periodical.Error when it is invalid.

to_rrule(rule)

@spec to_rrule(t()) :: String.t()

Renders a rule as RFC 5545 RRULE text.

to_sentence(rule)

@spec to_sentence(t()) :: String.t()

Renders a rule as an English sentence.