Recurrence rules that read and write both RFC 5545 RRULE and plain English.
An ephemeris is a table of recurring positions over time. This one holds recurrence rules: parse them from either syntax into one structure, compute occurrences from it, and render it back out in either syntax.
iex> {:ok, rule} = Ephemeris.parse("every last Sunday of the month")
iex> Ephemeris.to_rrule(rule)
"FREQ=MONTHLY;BYDAY=-1SU"
iex> {:ok, rule} = Ephemeris.parse("FREQ=MONTHLY;BYDAY=-1SU")
iex> Ephemeris.to_sentence(rule)
"every last Sunday of the month"
iex> {:ok, rule} = Ephemeris.parse("every 3rd Monday of the month")
iex> Ephemeris.next(rule, ~U[2026-01-01 09:00:00Z])
{:ok, ~U[2026-01-19 09:00:00Z]}Why both syntaxes
RRULE is the standard: portable, precise, and what a calendar application
speaks. It is also unreadable in a configuration file. Plain English is the
opposite on both counts. Holding one structure and rendering either means a
rule can be written the readable way, stored the portable way, and shown back
either way, without two implementations that can disagree.
What a rule is not
A rule says when something recurs and nothing else. It holds no process, no
callback, no timer and no notion of the current time — every calculation takes
an explicit reference DateTime. Scheduling belongs to whatever uses this.
Summary
Functions
Returns the first occurrence strictly after reference.
Parses either syntax into a rule.
Parses either syntax, raising Ephemeris.Error when it cannot.
Streams occurrences strictly after reference, in order.
Renders a rule as RFC 5545 RRULE text.
Renders a rule as an English sentence.
Functions
@spec next(Ephemeris.Rule.t(), DateTime.t()) :: {:ok, DateTime.t()} | {:error, Ephemeris.Error.t()}
Returns the first occurrence strictly after reference.
Strictly after, so feeding an occurrence back in yields the following one.
@spec parse(String.t()) :: {:ok, Ephemeris.Rule.t()} | {:error, Ephemeris.Error.t()}
Parses either syntax into a rule.
An expression containing = is read as RRULE, anything else as English.
That is unambiguous rather than a guess: RRULE is always KEY=VALUE pairs
and an English sentence never contains =.
Examples
iex> {:ok, rule} = Ephemeris.parse("FREQ=WEEKLY;BYDAY=MO")
iex> rule.frequency
:weekly
iex> {:ok, rule} = Ephemeris.parse("every Monday")
iex> rule.frequency
:weekly
@spec parse!(String.t()) :: Ephemeris.Rule.t()
Parses either syntax, raising Ephemeris.Error when it cannot.
@spec stream(Ephemeris.Rule.t(), DateTime.t()) :: Enumerable.t()
Streams occurrences strictly after reference, in order.
Lazy: a rule with no COUNT or UNTIL is unbounded, so take what you need.
@spec to_rrule(Ephemeris.Rule.t()) :: String.t()
Renders a rule as RFC 5545 RRULE text.
@spec to_sentence(Ephemeris.Rule.t()) :: String.t()
Renders a rule as an English sentence.