# `Ephemeris`
[🔗](https://github.com/joetjen/ephemeris/blob/main/lib/ephemeris.ex#L1)

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.

# `next`

```elixir
@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`

```elixir
@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!`

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

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

# `stream`

```elixir
@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`

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

Renders a rule as RFC 5545 `RRULE` text.

# `to_sentence`

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

Renders a rule as an English sentence.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
