# `Periodical.Recurrence`
[🔗](https://github.com/joetjen/periodical/blob/main/lib/periodical/recurrence.ex#L1)

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](https://github.com/joetjen/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]}

# `t`

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

A parsed recurrence rule.

# `next`

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

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

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

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

# `to_rrule`

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

Renders a rule as RFC 5545 `RRULE` text.

# `to_sentence`

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

Renders a rule as an English sentence.

---

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