# `Calendrical.Calendar`

Makes a hand-written calendar: one whose spine, `date_to_iso_days/3`
and `date_from_iso_days/1`, the author writes, with `leap_year?/1`,
`months_in_year/1` and `days_in_month/2`, and `leap_month/1` where the
calendar has a leap month. Every other answer, from the day of the week
to the ranges of a quarter, is derived from those and from the facts
the options state, as `c:Calendrical.info/0` carries them.

### Example

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

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

      @impl true
      def date_to_iso_days(year, month, day) do
        # ... the calendar's own calculation
      end

      @impl true
      def date_from_iso_days(iso_days) do
        # ... the calendar's own calculation
      end
    end

### Options

* `:epoch` (required) is the first day of the calendar's year 1, as a
  date in a calendar that has already been compiled, such as
  `~D[0622-03-20 Calendrical.Julian]`.

* `:cldr_calendar_type` is the CLDR calendar whose data names the
  months, days and eras, `:gregorian` by default.

* `:era_calendar_type` is the CLDR calendar whose eras the calendar
  counts years in, the CLDR calendar type by default.

* `:months_in_year` is the number of months in a year, or
  `{fewest, most}` where a leap year has more, as the Hebrew calendar's
  `{12, 13}`. The default is `12`.

* `:weeks` is the rule the calendar's own weeks follow: a keyword list
  with `:first_day`, 1 for Monday to 7 for Sunday, and
  `:min_days_in_first_week`, or `:from_first_day` for weeks counted from
  the first day of the year. The default is Monday and 1.

* `:year_zero?` is whether the calendar has a year 0, `true` by default;
  a calendar without one goes from year -1 to year 1.

* `:year_cycle` is the cycle the years run in, as the sexagenary cycle
  of 60, or `nil`.

* `:years_in_cycle` is the number of years after which the calendar's
  days and weekdays repeat, where they do, for sampling.

* `:location` is the place an astronomical calendar is reckoned at, a
  function of the ISO day number.

* `:month_lengths` are the lengths a month can have, by month, where the
  calendar states them rather than having them sampled.

* `:parsing_calendar` is the calendar a written date is parsed in, the
  calendar itself by default.

### Overriding

The six primitive `Calendar` callbacks, `leap_year?/1`,
`months_in_year/1`, `days_in_month/2`, `valid_date?/3`, `year_of_era/3`
and `day_of_era/3`, and the kernel, `leap_month/1`, `written_date/3`,
`date_from_written_date/3`, `shift/6` and `diff/3`, may be defined by
the calendar. Every other generated function is a delegation defined
before the calendar's own code, so a later definition of one is
unreachable: the compiler warns that its clause can never match, and
the generated answer stands.

---

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