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 monthRRULE 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
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
@type t() :: Ephemeris.Rule.t()
A parsed recurrence rule.
Functions
@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.
@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.
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.