User-defined Calendars

This guide explains how to define a new calendar in Calendrical by useing the Calendrical.Behaviour macro. It covers the macro options, the two functions every calendar must define itself, every overridable callback, the conventions for sharing logic across related calendars, and a worked example for each common calendar shape (year-offset, solar, tabular lunar, observational lunar, lunisolar, and composite).

Why a behaviour?

A calendar in Elixir is a module that implements the Calendar behaviour from the standard library. The Calendar behaviour requires ~30 callbacks covering date arithmetic, leap-year detection, month and day counting, parsing and formatting, ISO-day conversion, time-of-day handling, time-zone-aware shift operations, and date-string output. Calendrical adds another ~15 callbacks of its own (Calendrical behaviour) covering localization, period ranges, era handling, and CLDR calendar typing.

Calendrical.Behaviour is a defmacro __using__ template that generates sensible default implementations of every callback from a small number of options. A calendar that uses the behaviour only needs to:

1. Supply the :epoch option (mandatory) and any other options that differ from the defaults.

2. Define date_to_iso_days/3 and date_from_iso_days/1, the two functions that map between the calendar's {year, month, day} form and the universal proleptic-Gregorian ISO day number.

3. Override any callbacks whose default behaviour is wrong for the calendar (e.g. leap_year?/1, days_in_month/2, valid_date?/3).

Every callback generated by the behaviour is defoverridable, so you can replace as many or as few of them as you like. The built-in calendars range from ~80 lines (Calendrical.Buddhist) to ~290 lines (Calendrical.Hebrew), depending on how much customisation they require.

Quick start

defmodule MyApp.MyCalendar do
  use Calendrical.Behaviour,
    epoch: ~D[0001-01-01 Calendar.ISO],
    cldr_calendar_type: :gregorian

  @impl true
  def leap_year?(year), do: rem(year, 4) == 0

  def date_to_iso_days(year, month, day) do
    # ... calendar-specific calculation
  end

  def date_from_iso_days(iso_days) do
    # ... calendar-specific calculation
  end
end

That is the minimum: an epoch, a CLDR calendar type, an overridden leap_year?/1, and the two ISO-day conversion functions. Everything else (parsing, formatting, intervals, day-of-week, day-of-year, period ranges, …) is generated by the behaviour using the defaults.

Required: the two ISO-day conversion functions

Every calendar useing Calendrical.Behaviour must define these two functions itself. They are not generated by the behaviour because the conversion logic is the heart of what makes one calendar different from another.

date_to_iso_days(year, month, day)

Convert a calendar {year, month, day} to an integer ISO day number. The ISO day number is the count of days since the proleptic Gregorian epoch (1 January 0000 = 0). It is the same numbering used by Calendar.ISO.date_to_iso_days/3 and Date.to_gregorian_days/1, and it is the universal "lingua franca" that lets all Calendrical calendars interoperate via Date.convert/2.

def date_to_iso_days(year, month, day) do
  # for example, a year-offset calendar:
  Calendrical.Gregorian.date_to_iso_days(year + offset, month, day)
end

date_from_iso_days(iso_days)

The inverse: given an integer ISO day number, return the calendar {year, month, day} tuple.

def date_from_iso_days(iso_days) do
  {greg_year, month, day} = Calendrical.Gregorian.date_from_iso_days(iso_days)
  {greg_year - offset, month, day}
end

These two functions must be inverses: date_from_iso_days(date_to_iso_days(y, m, d)) == {y, m, d} for every valid {y, m, d} in the calendar. The behaviour uses both internally for date arithmetic, intervals, day-of-week computation, and so on, so any inconsistency between them will surface as test failures across the rest of the API.

Macro options

All options are passed as keyword arguments to the use macro:

use Calendrical.Behaviour,
  epoch: ~D[0622-03-20 Calendrical.Julian],
  cldr_calendar_type: :persian,
  months_in_ordinary_year: 12

Choosing the epoch

The epoch must be expressed in another calendar that has already been compiled by the time use Calendrical.Behaviour runs. In practice this means one of:

• Calendar.ISO — the standard library proleptic Gregorian.
• Calendrical.Gregorian — equivalent to Calendar.ISO but with CLDR support and a year offset of 0.
• Calendrical.Julian — proleptic Julian, useful for ancient calendars whose epoch is naturally a Julian date (Coptic, Ethiopic, Persian, Islamic).

# Persian (Hijri Shamsi): epoch is 20 March 622 Julian
epoch: ~D[0622-03-20 Calendrical.Julian]

# Coptic: epoch is 29 August 284 Julian (Era of Martyrs)
epoch: ~D[0284-08-29 Calendrical.Julian]

# Buddhist: 1 January 543 BCE Gregorian (proleptic, with year zero)
epoch: ~D[-0542-01-01 Calendrical.Gregorian]

The epoch is evaluated at compile time, converted to an ISO day number via the source calendar's own date_to_iso_days/3, and stored as the @epoch module attribute. The generated epoch/0 function returns this integer at runtime.

The behaviour also computes epoch_day_of_week/0 automatically by converting the epoch to Calendar.ISO and calling Date.day_of_week/1.

Generated and overridable callbacks

After use Calendrical.Behaviour, ..., the following functions are available in the calling module. All of them are defoverridable, so you can replace any of them.

Identity / configuration

Validity

Year and era

Periods

Period counts

Period ranges

Arithmetic

ISO-day conversion

Parsing and formatting

Era support

When the using module is compiled, an @after_compile hook automatically calls Calendrical.Era.define_era_module/1. This:

1. Reads the CLDR era data for the calendar's :cldr_calendar_type.
2. Generates a Calendrical.Era.<CalendarType> module containing a year_of_era/2 and day_of_era/1 lookup function.
3. Wires the calendar's default year_of_era/{1, 3} and day_of_era/3 to use this generated module.

For most calendars (Persian, Buddhist, Indian, ROC, …) this is exactly what you want — the CLDR era data has the correct era boundaries and your calendar gets era support for free.

A few calendars (Coptic, Ethiopic, Julian) use a simpler "positive year = era 1, negative year = era 0" convention that does not match the CLDR data. They override year_of_era/1, year_of_era/3, and day_of_era/3 directly:

def year_of_era(year) when year > 0, do: {year, 1}
def year_of_era(year) when year < 0, do: {abs(year), 0}

@impl true
def year_of_era(year, _month, _day), do: year_of_era(year)

If two calendars share the same :cldr_calendar_type (for example Calendrical.Chinese and Calendrical.LunarJapanese both use :chinese), the era module is created exactly once. The Calendrical.Era.define_era_module/1 function uses an ETS-based lock to coordinate creation under parallel compilation.

Worked examples

Year-offset over Gregorian (Buddhist, ROC)

The simplest possible calendar: take the proleptic Gregorian arithmetic and add a fixed year offset. This is how Calendrical.Buddhist, Calendrical.Roc, and Calendrical.Ethiopic.AmeteAlem are implemented.

defmodule MyApp.Buddhist do
  use Calendrical.Behaviour,
    epoch: ~D[-0542-01-01 Calendrical.Gregorian],
    cldr_calendar_type: :buddhist

  @offset 543

  @impl true
  def leap_year?(year), do: Calendrical.Gregorian.leap_year?(year - @offset)

  @impl true
  def days_in_month(year, month) do
    Calendrical.Gregorian.days_in_month(year - @offset, month)
  end

  def date_to_iso_days(year, month, day) do
    Calendrical.Gregorian.date_to_iso_days(year - @offset, month, day)
  end

  def date_from_iso_days(iso_days) do
    {gy, m, d} = Calendrical.Gregorian.date_from_iso_days(iso_days)
    {gy + @offset, m, d}
  end
end

That is the entire calendar — about 25 lines plus moduledoc. Every other callback (parsing, day-of-week, intervals, localization, period ranges, sigils, …) comes for free from the behaviour.

A 13-month tabular calendar (Coptic, Ethiopic)

A 13-month calendar overrides one extra option (:months_in_ordinary_year) plus the callbacks that are 13-month-aware:

defmodule MyApp.MyCoptic do
  use Calendrical.Behaviour,
    epoch: ~D[0284-08-29 Calendrical.Julian],
    cldr_calendar_type: :coptic,
    months_in_ordinary_year: 13,
    months_in_leap_year: 13

  @impl true
  def leap_year?(year), do: Integer.mod(year, 4) == 3

  @impl true
  def days_in_month(year, 13), do: if(leap_year?(year), do: 6, else: 5)
  def days_in_month(_year, month) when month in 1..12, do: 30

  @impl true
  def days_in_year(year), do: if(leap_year?(year), do: 366, else: 365)

  @impl true
  def quarter_of_year(_year, _month, _day), do: {:error, :not_defined}

  @impl true
  def day_of_week(year, month, day, :default) do
    iso = date_to_iso_days(year, month, day)
    {Integer.mod(iso + 5, 7) + 1, 6, 5}  # Saturday = 6, Friday = 5
  end

  def date_to_iso_days(year, month, day) do
    epoch() - 1 + 365 * (year - 1) + div(year, 4) + 30 * (month - 1) + day
  end

  def date_from_iso_days(iso_days) do
    # ... (see lib/calendrical/calendars/coptic.ex for the full formula)
  end
end

A lunisolar calendar with leap months (Hebrew)

The Hebrew calendar adds two complications:

1. A discontinuous month numbering: month 6 (Adar I) only exists in leap years.
2. A _yeartype_leap localization variant: month 7 is "Adar" in ordinary years and "Adar II" in leap years.

The first is handled by overriding valid_date?/3 to reject month 6 in non-leap years. The second is handled by overriding month_of_year/3 to return {7, :leap} in leap years; Calendrical.localize/3 then automatically looks up the _yeartype_leap variant from the CLDR data.

defmodule MyApp.MyHebrew do
  use Calendrical.Behaviour,
    epoch: Date.new!(-3761, 10, 7, Calendrical.Julian),
    cldr_calendar_type: :hebrew,
    months_in_ordinary_year: 12,
    months_in_leap_year: 13

  @impl true
  def leap_year?(year), do: Integer.mod(7 * year + 1, 19) < 7

  @impl true
  def valid_date?(year, 6, _day), do: leap_year?(year)
  def valid_date?(year, month, day) when month in 1..13 and day in 1..30 do
    day <= days_in_month(year, month)
  end
  def valid_date?(_year, _month, _day), do: false

  @impl true
  def month_of_year(year, 7, _day) do
    if leap_year?(year), do: {7, :leap}, else: 7
  end
  def month_of_year(_year, month, _day), do: month

  # ... days_in_month/2, date_to_iso_days/3, date_from_iso_days/1
end

See lib/calendrical/calendars/hebrew.ex for the full implementation including the molad of Tishri and dehiyyah postponement rules.

An astronomical calendar (Persian, observational Islamic)

Astronomical calendars use the Astro library to compute month and year boundaries from actual astronomical events. The pattern is the same: override the few callbacks that need astronomical data, and let everything else use the defaults.

defmodule MyApp.MyPersian do
  use Calendrical.Behaviour,
    epoch: ~D[0622-03-20 Calendrical.Julian],
    cldr_calendar_type: :persian

  @impl true
  def leap_year?(year) do
    new_year = date_to_iso_days(year, 1, 1)
    next_year = date_to_iso_days(year + 1, 1, 1)
    next_year - new_year == 366
  end

  def date_to_iso_days(year, _month, _day) do
    # ... use Astro.equinox/2 to find the vernal equinox in Tehran
    #     for the relevant Gregorian year
  end

  def date_from_iso_days(_iso_days) do
    # ... inverse: find the most recent Persian new year on or before
    #     the iso_days
  end
end

See lib/calendrical/calendars/persian.ex for the complete implementation, and lib/calendrical/calendars/islamic/observational.ex and rgsa.ex for crescent-visibility-based calendars.

Composite calendars

A composite calendar is one that uses one base calendar before a specified date and a different calendar after. It is built with the separate Calendrical.Composite macro rather than Calendrical.Behaviour directly. Use this when you need to model a historical calendar reform — the canonical example being the European Julian-to-Gregorian transition.

defmodule MyApp.England do
  use Calendrical.Composite,
    calendars: [
      ~D[1155-03-25 Calendrical.Julian.March25],
      ~D[1751-03-25 Calendrical.Julian.Jan1],
      ~D[1752-09-14 Calendrical.Gregorian]
    ],
    base_calendar: Calendrical.Julian
end

The Calendrical.Composite macro accepts:

The composite calendar:

• Delegates every callback (leap_year?/1, days_in_month/2, date_to_iso_days/3, day_of_week/4, …) to whichever base calendar is in effect for the date in question.

• Treats the days "skipped" by a transition (e.g. 3–13 September 1752 in the English calendar) as invalid — valid_date?/3 returns false for them.

• Round-trips correctly: Date.shift(~D[1752-09-02 MyApp.England], day: 1) returns ~D[1752-09-14 MyApp.England].

You can chain any number of transitions and combine any pair of calendars. See lib/calendrical/calendars/england.ex and lib/calendrical/calendars/russia.ex for two pre-built examples.

Sharing logic across related calendars

When two calendars share most of their algorithms but differ in one or two values (for example: Calendrical.Islamic.Civil and Calendrical.Islamic.Tbla differ only in epoch; Calendrical.Islamic.Observational and Calendrical.Islamic.Rgsa differ only in the observation location), the convention is:

1. Put the shared algorithm in a private helper module that takes the varying value as a parameter.
2. Have each public calendar use Calendrical.Behaviour with the appropriate options.
3. Have the public callbacks delegate to the helper.

defmodule Calendrical.Islamic.Tabular do
  @moduledoc false
  def leap_year?(year), do: Integer.mod(14 + 11 * year, 30) < 11

  def date_to_iso_days(year, month, day, epoch) do
    # ... formula parameterised by epoch
  end

  def date_from_iso_days(iso_days, epoch) do
    # ...
  end
end

defmodule Calendrical.Islamic.Civil do
  use Calendrical.Behaviour,
    epoch: ~D[0622-07-19 Calendrical.Gregorian],
    cldr_calendar_type: :islamic_civil

  alias Calendrical.Islamic.Tabular

  @impl true
  def leap_year?(year), do: Tabular.leap_year?(year)

  def date_to_iso_days(year, month, day) do
    Tabular.date_to_iso_days(year, month, day, epoch())
  end

  def date_from_iso_days(iso_days) do
    Tabular.date_from_iso_days(iso_days, epoch())
  end
end

This pattern keeps each public calendar small (~70-90 lines) while the shared algorithm lives in one place.

When Calendrical.Behaviour is not the right tool

Calendrical.Behaviour is designed for algorithmic calendars — calendars whose date arithmetic can be expressed as a closed-form computation. It is not the right tool when:

• You need a week-based calendar with non-standard week numbering or quarter-of-year structure. Use Calendrical.Base.Week directly via Calendrical.new/3, which generates a calendar from a weeks_in_month configuration.

• You need a month-based calendar that varies its first month or its year-anchor month for fiscal/financial purposes. Use Calendrical.Base.Month directly via Calendrical.new/3 or look at the pre-built Calendrical.FiscalYear.<TERR> calendars.

• You need a composite calendar that uses different base calendars for different date ranges. Use Calendrical.Composite (described above).

In all three cases, the resulting module still implements the standard Calendar and Calendrical behaviours and interoperates with everything else in the library — it just gets its callbacks from a different macro.