Ephemeris (Ephemeris v0.1.0)

Copy Markdown View Source

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

next(rule, reference)

@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.

parse(expression)

@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

parse!(expression)

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

Parses either syntax, raising Ephemeris.Error when it cannot.

stream(rule, reference)

@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.

to_rrule(rule)

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

Renders a rule as RFC 5545 RRULE text.

to_sentence(rule)

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

Renders a rule as an English sentence.