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

One recurrence rule, held in the structure both representations share.

A rule says *when* something recurs and nothing else: it carries no start
instant, no process, no callback and no notion of the current time. Every
calculation takes an explicit reference `DateTime`, which is what makes a rule
a value you can compare, store and render rather than a live thing.

The field names follow RFC 5545 §3.3.10, because that is the standard both
representations describe. `Ephemeris.parse/1` builds one from either syntax,
and `Ephemeris.to_rrule/1` and `Ephemeris.to_sentence/1` render it back.

## Fields

| Field | RRULE part | Meaning |
| --- | --- | --- |
| `:frequency` | `FREQ` | The base period the rule repeats over |
| `:interval` | `INTERVAL` | How many of those periods between occurrences |
| `:count` | `COUNT` | Stop after this many occurrences |
| `:until` | `UNTIL` | Stop at this instant, inclusive |
| `:week_start` | `WKST` | Which weekday a week begins on, affecting weekly intervals |
| `:by_second` | `BYSECOND` | Seconds within the minute |
| `:by_minute` | `BYMINUTE` | Minutes within the hour |
| `:by_hour` | `BYHOUR` | Hours within the day |
| `:by_day` | `BYDAY` | Weekdays, optionally with an ordinal such as `{-1, :sunday}` |
| `:by_month_day` | `BYMONTHDAY` | Days of the month, negative counting from the end |
| `:by_year_day` | `BYYEARDAY` | Days of the year, negative counting from the end |
| `:by_week_number` | `BYWEEKNO` | ISO week numbers |
| `:by_month` | `BYMONTH` | Months of the year |
| `:by_set_position` | `BYSETPOS` | Which of a period's candidate occurrences to keep |

`:count` and `:until` are mutually exclusive, as the standard requires.

# `day_spec`

```elixir
@type day_spec() :: weekday() | {integer(), weekday()}
```

A weekday, optionally restricted to one occurrence within the period.

`{-1, :sunday}` is the last Sunday, `{3, :monday}` the third Monday. A bare
weekday means every one of them.

# `frequency`

```elixir
@type frequency() ::
  :secondly | :minutely | :hourly | :daily | :weekly | :monthly | :yearly
```

The base period a rule repeats over.

# `t`

```elixir
@type t() :: %Ephemeris.Rule{
  by_day: [day_spec()],
  by_hour: [0..23],
  by_minute: [0..59],
  by_month: [1..12],
  by_month_day: [integer()],
  by_second: [0..60],
  by_set_position: [integer()],
  by_week_number: [integer()],
  by_year_day: [integer()],
  count: pos_integer() | nil,
  frequency: frequency(),
  interval: pos_integer(),
  until: DateTime.t() | nil,
  week_start: weekday()
}
```

A recurrence rule.

# `weekday`

```elixir
@type weekday() ::
  :monday | :tuesday | :wednesday | :thursday | :friday | :saturday | :sunday
```

A weekday, spelled out rather than numbered.

# `day_number`

```elixir
@spec day_number(weekday()) :: 1..7
```

Returns the ISO day number for a weekday, Monday being 1.

## Examples

    iex> Ephemeris.Rule.day_number(:monday)
    1

    iex> Ephemeris.Rule.day_number(:sunday)
    7

# `frequencies`

```elixir
@spec frequencies() :: [frequency()]
```

Returns every supported frequency, in ascending period order.

# `weekday`

```elixir
@spec weekday(1..7) :: weekday()
```

Returns the weekday for an ISO day number.

## Examples

    iex> Ephemeris.Rule.weekday(1)
    :monday

# `weekdays`

```elixir
@spec weekdays() :: [weekday()]
```

Returns every weekday, Monday first.

---

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