Tempo.DateRule (Tempo v2.1.0)

Reads date rules: the yearly dates people write, 2nd Monday in June, Friday after 4th Thursday in November, easter -2, 15 Nisan, chinese 01-0-01, march equinox in Asia/Tokyo, into the Tempo recurrences they mean.

The grammar is the one date-holidays writes its holidays in, read as its parser, date-holidays-parser, reads it: a fixed date, a weekday step from one, Easter, an equinox or a solstice, a date in the Islamic, Hebrew, Persian, Julian, Chinese, Korean or Vietnamese calendar, with a span, an observed day (and if sunday then next monday), year and weekday filters, since and prior to. ISO 8601-2 and RFC 5545's RRULE (Tempo.RRule) say the same things in forms made for machines to exchange; a date rule is the form people write.

parse/2 reads a rule, and parse!/2 raises its error. The date rules guide shows how to write and use rules, with the dates each part falls on, and the date rule grammar is the reference for every part a rule may have.

A part of the grammar the reading does not take returns an error naming it: the Bengali calendar, a solar term of the Korean or Vietnamese calendar, if equal, and an if is holiday move by more than one or back.

Summary

Functions

parse(rule, options \\ [])

Reads a date rule into the Tempo recurrence it means.

parse!(rule, options \\ [])

parse/2, returning its answer or raising the error.

Functions

parse(rule, options \\ [])

@spec parse(String.t(), keyword()) :: {:ok, Tempo.t()} | {:error, Exception.t()}

Reads a date rule into the Tempo recurrence it means.

Arguments

rule is a date rule, such as "2nd Monday in June".
options is a keyword list of options.

Options

:falls_on is what a rule that depends on other dates is decided against (a bridge, 09-22 if 09-21 is holiday, or a move, if is holiday then next monday): a map the metadata of another member of a set holds. The default is %{type: type}, the type the rule names, :public where it names none.
:observed is how a rule's observed days are read: :as_written (the default); :moved, each clause moving the date, so that and if sunday then next monday gives the Monday in place of a Sunday rather than beside it; or :none, the date with no observed day, which leaves a rule that begins substitutes, only observed days, no date: an empty set.
:active is a list of {from, to} windows of Date.t/0, from included and to not, either nil for an open end: the rule falls in the years whose date is in one of them, and within its own since and prior to, as date-holidays' active periods say.
:disable is a list of Date.t/0 the rule's date is moved from: where one is the rule's date in its year, that year's date is left out.
:enable is a list of Date.t/0 added in the year of a disabled date, the day a holiday is moved to.
:replaced_by is a list of rules that begin substitutes, each alone or as {rule, active: windows}, that may stand in for the rule's date: one of the same date, gated by its years alone, takes its trigger weekdays from a rule that is a plain date with no observed day of its own, in the years it is in force. The others are passed over, so the substitutes entries of a dataset may be given to each of its rules.

Returns

{:ok, expression}, a Tempo.t/0: a yearly recurrence, a recurrence set of a date and its observed days, or a conditional member for a rule that depends on other dates. An observed day carries %{substitute: true} in its metadata.
{:error, %Tempo.ParseError{}} for a rule that cannot be read, naming where reading stopped or which part is not read, or
{:error, exception} for a date the rule names that its calendar does not have, such as a Tempo.InvalidDateError for the month of 13-01.

Examples

iex> {:ok, rule} = Tempo.DateRule.parse("12-25")
iex> Tempo.to_iso8601(rule)
{:ok, "R/../P1Y/FL12M25DN"}

iex> {:ok, rule} = Tempo.DateRule.parse("2nd Monday in June")
iex> Tempo.to_iso8601(rule)
{:ok, "R/../P1Y/FL6M1K2IN"}

iex> {:ok, new_years_day} = Tempo.DateRule.parse("01-01 and if sunday then next monday", observed: :none)
iex> Tempo.to_iso8601(new_years_day)
{:ok, "R/../P1Y/FL1M1DN"}

iex> {:error, %Tempo.ParseError{rest: "a full moon"}} = Tempo.DateRule.parse("12-25 on a full moon")

parse!(rule, options \\ [])

@spec parse!(String.t(), keyword()) :: Tempo.t()

parse/2, returning its answer or raising the error.

Arguments

The arguments are those of parse/2.

Returns

What parse/2 returns as {:ok, answer}, the answer alone. The error it returns as {:error, exception} is raised.

Examples

iex> Tempo.DateRule.parse!("easter -2")
...> |> Tempo.to_iso8601!()
"R/../P1Y/FLL(easter)eN/P-3D5K1IN"