# `Calendrical.Calendar.Lunisolar`

Makes a lunisolar calendar reckoned from the sky: a year of twelve or
thirteen lunar months that begins at the second new moon after the
winter solstice, with the leap month placed by the solar terms, as the
Chinese, Korean, Vietnamese and traditional Japanese calendars are.

The maker supplies the whole kernel from `Calendrical.Lunisolar`, which
is parametrised by the calendar's epoch and the place it is reckoned
at, and the functions a lunisolar calendar is asked beyond the kernel:
a date from a traditional month, the Gregorian date of a lunar date,
the new year of a Gregorian year, and the sexagenary cycle and year of
a year and the year they name. A module keeps its own extras, as the
festivals, beside them.

### Options

* `:epoch` is the first day of the calendar's year 1, as a `t:Date.t/0`.

* `:location` is the place the calendar is reckoned at, a function of
  the ISO day number giving `{latitude, longitude, altitude, offset}`
  as `Astro` takes them.

* `:cldr_calendar_type` is the CLDR calendar whose data names the
  months, `:chinese` by default.

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

### Supported years

A calendar answers for the 40,001 years numbered, from the Gregorian
year of its epoch, as Gregorian years -20,000 to 20,000:
`Calendrical.Chinese` years -17,363 to 22,637, which run from late
-20,001 to early 20,001. Beyond them the new moons the calendar is
reckoned from drift from their mean timing faster than a search can
follow, so:

* `valid_date?/3` is `false`, and a question about a date (`year/1`,
  `days_in_year/1`, `day_of_week/4`, `year_of_era/3` and the rest)
  answers `{:error, %Calendrical.InvalidDateError{}}`, as for any date the
  calendar lacks.

* `new/3` and `days_in_month/2` return
  `{:error, %Calendrical.UnsupportedDateRangeError{}}`.

* `date_to_iso_days/3`, `date_from_iso_days/1`, `leap_year?/1`,
  `leap_month/1`, `leap_month?/2`, `months_in_year/1` and, for a
  Gregorian year outside -20,000 to
  20,000, `gregorian_date_for_lunar/3` raise
  `Calendrical.UnsupportedDateRangeError`, as the sighting Islamic
  calendars do outside their ephemeris.

### Examples

    defmodule Chinese do
      use Calendrical.Calendar.Lunisolar,
        epoch: ~D[-2636-02-15],
        location: &__MODULE__.location/1

      def location(_iso_days), do: {39.9, 116.4, 44, 8 / 24}
    end

---

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