Ephemeris.Rule (Ephemeris v0.1.0)

Copy Markdown View Source

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

FieldRRULE partMeaning
:frequencyFREQThe base period the rule repeats over
:intervalINTERVALHow many of those periods between occurrences
:countCOUNTStop after this many occurrences
:untilUNTILStop at this instant, inclusive
:week_startWKSTWhich weekday a week begins on, affecting weekly intervals
:by_secondBYSECONDSeconds within the minute
:by_minuteBYMINUTEMinutes within the hour
:by_hourBYHOURHours within the day
:by_dayBYDAYWeekdays, optionally with an ordinal such as {-1, :sunday}
:by_month_dayBYMONTHDAYDays of the month, negative counting from the end
:by_year_dayBYYEARDAYDays of the year, negative counting from the end
:by_week_numberBYWEEKNOISO week numbers
:by_monthBYMONTHMonths of the year
:by_set_positionBYSETPOSWhich of a period's candidate occurrences to keep

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

Summary

Types

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

The base period a rule repeats over.

t()

A recurrence rule.

A weekday, spelled out rather than numbered.

Functions

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

Returns every supported frequency, in ascending period order.

Returns the weekday for an ISO day number.

Returns every weekday, Monday first.

Types

day_spec()

@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()

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

The base period a rule repeats over.

t()

@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()

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

A weekday, spelled out rather than numbered.

Functions

day_number(atom)

@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()

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

Returns every supported frequency, in ascending period order.

weekday(int)

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

Returns the weekday for an ISO day number.

Examples

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

weekdays()

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

Returns every weekday, Monday first.