lua-calendrica

# Module `calendrica`

Calendar conversion API.

All dates are stored internally as RD (Rata Die) fixed integers. Calendar fields (`year`, `month`, `day`, …) are computed lazily on first access and cached on the date object.

### Usage:

    local calendrica = require("calendrica")
    local d  = calendrica.new_date({year=2024, month=4, day=23}, calendrica.cal_gregorian)
    local d2 = calendrica.as_date(d, calendrica.cal_hebrew)
    print(d2.year, d2.month, d2.day)

### Info:

- Release: 0.1 2026-07-19

##

new_calendar (name, granularities, from_rd[, to_rd]) | Create a new calendar definition.
granularity_names (calendar) | Return the ordered granularity names of a calendar.
new_date (fields, calendar) | Construct a date from named fields and a calendar.
as_date (date, calendar) | Convert a date object to a different calendar.
as_fixed (date) | Return the fixed (RD) integer for a date object.
today ([calendar]) | Return today's date in the given calendar.
cal_gregorian | Proleptic Gregorian calendar.
cal_julian | Proleptic Julian calendar.
cal_roman | Roman calendar (Julian-based).
cal_iso | ISO week-date calendar.
cal_egyptian | Ancient Egyptian calendar.
cal_armenian | Armenian calendar (structurally identical to Egyptian).
cal_coptic | Coptic calendar.
cal_ethiopic | Ethiopic calendar.
cal_islamic | Arithmetic Islamic (Hijri) calendar.
cal_islamic_observational | Observational Islamic calendar (astronomical).
cal_islamic_tbla | Saudi Islamic calendar (Umm al-Qura approximation).
cal_islamic_umalqura | Umm al-Qura Islamic calendar.
cal_islamic_saudi | Observational Saudi Islamic calendar.
cal_islamic_umalqura_astronomical | Astronomical Umm al-Qura calendar (conjunction before Mecca sunset).
cal_islamic_turkish | Turkish Islamic calendar (Diyanet crescent visibility from Ankara).
cal_hebrew | Arithmetic Hebrew calendar.
cal_hebrew_observational | Observational Hebrew calendar (astronomical).
cal_persian | Astronomical Persian calendar.
cal_persian_arithmetic | Arithmetic Persian calendar.
cal_french | Astronomical French Revolutionary calendar.
cal_french_arithmetic | Arithmetic French Revolutionary calendar.
cal_bahai | Arithmetic Bahá'í calendar.
cal_bahai_astronomical | Astronomical Bahá'í calendar.
cal_mayan_long_count | Mayan Long Count calendar.
cal_mayan_haab | Mayan Haab calendar (read-only).
cal_mayan_tzolkin | Mayan Tzolkin calendar (read-only).
cal_aztec_xihuitl | Aztec Xihuitl calendar (read-only).
cal_aztec_tonalpohualli | Aztec Tonalpohualli calendar (read-only).
cal_balinese | Balinese Pawukon calendar (read-only).
cal_chinese | Chinese calendar.
cal_japanese | Japanese lunisolar calendar.
cal_korean | Korean lunisolar calendar.
cal_vietnamese | Vietnamese lunisolar calendar.
cal_old_hindu_solar | Old Hindu solar calendar (Arya Siddhanta).
cal_old_hindu_lunar | Old Hindu lunar calendar (Arya Siddhanta).
cal_hindu_solar | Modern Hindu solar calendar (Orissa rule).
cal_hindu_solar_astronomical | Astronomical Hindu solar calendar (Tamil rule).
cal_hindu_lunar | Modern Hindu lunar calendar.
cal_hindu_lunar_astronomical | Astronomical Hindu lunar calendar.
cal_tibetan | Tibetan calendar.
cal_icelandic | Icelandic calendar.
cal_akan | Akan day-name cycle (read-only).
cal_auc | Ab Urbe Condita (AUC) year numbering on the Julian calendar.
cal_olympiad | Greek Olympiad numbering on the Julian calendar.
cal_samaritan | Samaritan calendar.
cal_babylonian | Babylonian calendar (astronomical).
holiday (name, g_year) | Return occurrences of a named holiday in a Gregorian year as date objects.
holidays (g_year) | Return all holidays occurring in a Gregorian year, sorted by date.
holiday_names () | Return a sorted list of all registered holiday names.
calendar_names () | Return a sorted list of all built-in calendar names.
location (latitude, longitude, elevation, zone) | Construct a location for use with astronomical functions.
lunar_phase (date) | Lunar phase (0–360°) at midnight of `date`.
new_moons (g_year) | List of new-moon date objects falling in Gregorian year `g_year`.
full_moons (g_year) | List of full-moon date objects falling in Gregorian year `g_year`.
sunrise (date, loc) | Standard time of sunrise on `date` at `loc`, or nil if none.
sunset (date, loc) | Standard time of sunset on `date` at `loc`, or nil if none.
moonrise (date, loc) | Standard time of moonrise on `date` at `loc`, or nil if none.
moonset (date, loc) | Standard time of moonset on `date` at `loc`, or nil if none.

##

new_calendar (name, granularities, from_rd[, to_rd])
  Create a new calendar definition. `from_rd` and `to_rd` are the raw module functions that use positional tables; `new_calendar` wraps them automatically using `granularities` as the key list.

  ### Parameters:

  - name string Unique calendar name.
  - granularities {string,...} Ordered field names, e.g. `{"year","month","day"}`.
  - from_rd func Raw function: RD → positional table.
  - to_rd func Raw function: positional table → RD. Omit (or pass `nil`) for read-only calendars that cannot be used as a source in `new_date`. (optional)

  ### Returns:

  table Calendar object for use with `new_date`, `as_date`, and `granularity_names`.
granularity_names (calendar)
  Return the ordered granularity names of a calendar.

  ### Parameters:

  - calendar table A calendar object.

  ### Returns:

  {string,...} Ordered list of field name strings.
new_date (fields, calendar)
  Construct a date from named fields and a calendar. The calendar must have a `to_rd` function (i.e. must not be read-only).

  ### Parameters:

  - fields table Named field table; keys must match the calendar's granularity names.
  - calendar table or string Calendar object or calendar name string (e.g. `"gregorian"`).

  ### Returns:

  table Date object. Fields are accessible by name (e.g. `d.year`).

  ### Raises:

  If the calendar is unknown or read-only.
as_date (date, calendar)
  Convert a date object to a different calendar. The underlying RD value is reused; no arithmetic is performed.

  ### Parameters:

  - date table A date object (as returned by `new_date`, `as_date`, or `today`).
  - calendar table or string Target calendar object or name string.

  ### Returns:

  table New date object expressed in the target calendar.

  ### Raises:

  If the calendar is unknown.
as_fixed (date)
  Return the fixed (RD) integer for a date object.

  ### Parameters:

  - date table A date object (as returned by `new_date`, `as_date`, or `today`).

  ### Returns:

  number Fixed date (Rata Die integer).
today ([calendar])
  Return today's date in the given calendar.

  ### Parameters:

  - calendar table or string Calendar object or name string. Defaults to `cal_gregorian`. (optional)

  ### Returns:

  table Date object for today.

  ### Raises:

  If the calendar name is unknown.
cal_gregorian
  Proleptic Gregorian calendar. Granularities: `year`, `month`, `day`.
cal_julian
  Proleptic Julian calendar. Granularities: `year`, `month`, `day`.
cal_roman
  Roman calendar (Julian-based). Granularities: `year`, `month`, `event`, `count`, `leap`. `event` is one of `calendrica-julian`'s `KALENDS`, `NONES`, or `IDES` constants.
cal_iso
  ISO week-date calendar. Granularities: `year`, `week`, `day`.
cal_egyptian
  Ancient Egyptian calendar. Granularities: `year`, `month`, `day`.
cal_armenian
  Armenian calendar (structurally identical to Egyptian). Granularities: `year`, `month`, `day`.
cal_coptic
  Coptic calendar. Granularities: `year`, `month`, `day`.
cal_ethiopic
  Ethiopic calendar. Granularities: `year`, `month`, `day`.
cal_islamic
  Arithmetic Islamic (Hijri) calendar. Granularities: `year`, `month`, `day`.
cal_islamic_observational
  Observational Islamic calendar (astronomical). Granularities: `year`, `month`, `day`.
cal_islamic_tbla
  Saudi Islamic calendar (Umm al-Qura approximation). Granularities: `year`, `month`, `day`. Islamic TBLA calendar (Thursday epoch). Granularities: `year`, `month`, `day`.
cal_islamic_umalqura
  Umm al-Qura Islamic calendar. Granularities: `year`, `month`, `day`.
cal_islamic_saudi
  Observational Saudi Islamic calendar. Granularities: `year`, `month`, `day`.
cal_islamic_umalqura_astronomical
  Astronomical Umm al-Qura calendar (conjunction before Mecca sunset). Granularities: `year`, `month`, `day`.
cal_islamic_turkish
  Turkish Islamic calendar (Diyanet crescent visibility from Ankara). Granularities: `year`, `month`, `day`.
cal_hebrew
  Arithmetic Hebrew calendar. Granularities: `year`, `month`, `day`.
cal_hebrew_observational
  Observational Hebrew calendar (astronomical). Granularities: `year`, `month`, `day`.
cal_persian
  Astronomical Persian calendar. Granularities: `year`, `month`, `day`.
cal_persian_arithmetic
  Arithmetic Persian calendar. Granularities: `year`, `month`, `day`.
cal_french
  Astronomical French Revolutionary calendar. Granularities: `year`, `month`, `day`.
cal_french_arithmetic
  Arithmetic French Revolutionary calendar. Granularities: `year`, `month`, `day`.
cal_bahai
  Arithmetic Bahá'í calendar. Granularities: `major`, `cycle`, `year`, `month`, `day`.
cal_bahai_astronomical
  Astronomical Bahá'í calendar. Granularities: `major`, `cycle`, `year`, `month`, `day`.
cal_mayan_long_count
  Mayan Long Count calendar. Granularities: `baktun`, `katun`, `tun`, `uinal`, `kin`.
cal_mayan_haab
  Mayan Haab calendar (read-only). Granularities: `month`, `day`. Cannot be used as a source for `new_date` as Haab alone does not uniquely determine a date.
cal_mayan_tzolkin
  Mayan Tzolkin calendar (read-only). Granularities: `number`, `name`. Cannot be used as a source for `new_date` as Tzolkin alone does not uniquely determine a date.
cal_aztec_xihuitl
  Aztec Xihuitl calendar (read-only). Granularities: `month`, `day`.
cal_aztec_tonalpohualli
  Aztec Tonalpohualli calendar (read-only). Granularities: `number`, `name`.
cal_balinese
  Balinese Pawukon calendar (read-only). Granularities: `luang`, `dwiwara`, `triwara`, `caturwara`, `pancawara`, `sadwara`, `saptawara`, `asatawara`, `sangawara`, `dasawara`. The Pawukon cycle does not uniquely determine a fixed date.
cal_chinese
  Chinese calendar. Granularities: `cycle`, `year`, `month`, `leap`, `day`.
cal_japanese
  Japanese lunisolar calendar. Granularities: `cycle`, `year`, `month`, `leap`, `day`.
cal_korean
  Korean lunisolar calendar. Granularities: `year`, `month`, `leap`, `day`.
cal_vietnamese
  Vietnamese lunisolar calendar. Granularities: `cycle`, `year`, `month`, `leap`, `day`.
cal_old_hindu_solar
  Old Hindu solar calendar (Arya Siddhanta). Granularities: `year`, `month`, `day`.
cal_old_hindu_lunar
  Old Hindu lunar calendar (Arya Siddhanta). Granularities: `year`, `month`, `leap`, `day`.
cal_hindu_solar
  Modern Hindu solar calendar (Orissa rule). Granularities: `year`, `month`, `day`.
cal_hindu_solar_astronomical
  Astronomical Hindu solar calendar (Tamil rule). Granularities: `year`, `month`, `day`.
cal_hindu_lunar
  Modern Hindu lunar calendar. Granularities: `year`, `month`, `leap_month`, `day`, `leap_day`.
cal_hindu_lunar_astronomical
  Astronomical Hindu lunar calendar. Granularities: `year`, `month`, `leap_month`, `day`, `leap_day`.
cal_tibetan
  Tibetan calendar. Granularities: `year`, `month`, `leap_month`, `day`, `leap_day`.
cal_icelandic
  Icelandic calendar. Granularities: `year`, `season`, `week`, `weekday`.
cal_akan
  Akan day-name cycle (read-only). Granularities: `prefix`, `stem`. The Akan name does not uniquely determine a fixed date.
cal_auc
  Ab Urbe Condita (AUC) year numbering on the Julian calendar. Granularities: `year`, `month`, `day`. Year 1 AUC = 753 BCE (Julian).
cal_olympiad
  Greek Olympiad numbering on the Julian calendar. Granularities: `cycle`, `year`, `month`, `day`. Cycle 1, year 1 = 776 BCE (Julian). `year` is 1–4 within the 4-year cycle.
cal_samaritan
  Samaritan calendar. Granularities: `year`, `month`, `day`.
cal_babylonian
  Babylonian calendar (astronomical). Granularities: `year`, `month`, `leap`, `day`.
holiday (name, g_year)
  Return occurrences of a named holiday in a Gregorian year as date objects.

  ### Parameters:

  - name string Holiday name (e.g. `"easter"`, `"hanukkah"`). See `holiday_names` for the full list.
  - g_year number Gregorian year.

  ### Returns:

  {table,...} List of date objects (may be empty if the holiday does not fall in the given year).

  ### Raises:

  If `name` is not a registered holiday.
holidays (g_year)
  Return all holidays occurring in a Gregorian year, sorted by date.

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  {{name=string,dates={table,...}},...} List of `{name, dates}` records, one per holiday that has at least one occurrence in the year.
holiday_names ()
  Return a sorted list of all registered holiday names.

  ### Returns:

  {string,...}
calendar_names ()
  Return a sorted list of all built-in calendar names.

  ### Returns:

  {string,...}
location (latitude, longitude, elevation, zone)
  Construct a location for use with astronomical functions.

  ### Parameters:

  - latitude number Degrees north (negative = south).
  - longitude number Degrees east (negative = west).
  - elevation number Metres above sea level.
  - zone number UTC offset in hours (e.g. 2 for UTC+2).

  ### Returns:

  table Location object.
lunar_phase (date)
  Lunar phase (0–360°) at midnight of `date`. 0 = new moon, 90 = first quarter, 180 = full moon, 270 = last quarter.

  ### Parameters:

  - date table A date object.

  ### Returns:

  number Degrees.
new_moons (g_year)
  List of new-moon date objects falling in Gregorian year `g_year`.

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  {table,...} Date objects (in cal_gregorian) for each new moon.
full_moons (g_year)
  List of full-moon date objects falling in Gregorian year `g_year`.

  ### Parameters:

  - g_year number Gregorian year.

  ### Returns:

  {table,...} Date objects (in cal_gregorian) for each full moon.
sunrise (date, loc)
  Standard time of sunrise on `date` at `loc`, or nil if none.

  ### Parameters:

  - date table A date object.
  - loc table A location (from `location`).

  ### Returns:

  table or nil `{hour, minute, second, zone}` or nil.
sunset (date, loc)
  Standard time of sunset on `date` at `loc`, or nil if none.

  ### Parameters:

  - date table A date object.
  - loc table A location (from `location`).

  ### Returns:

  table or nil `{hour, minute, second, zone}` or nil.
moonrise (date, loc)
  Standard time of moonrise on `date` at `loc`, or nil if none.

  ### Parameters:

  - date table A date object.
  - loc table A location (from `location`).

  ### Returns:

  table or nil `{hour, minute, second, zone}` or nil.
moonset (date, loc)
  Standard time of moonset on `date` at `loc`, or nil if none.

  ### Parameters:

  - date table A date object.
  - loc table A location (from `location`).

  ### Returns:

  table or nil `{hour, minute, second, zone}` or nil.

generated by LDoc 1.5.0 Last updated 2026-07-19 03:28:25