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

granularity_names (calendar)

Return the ordered granularity names of a calendar.

Parameters:

calendar table A calendar object.

Returns:

{string,...}

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

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

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

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

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,...}

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,...}},...}

holiday_names ()

Return a sorted list of all registered holiday names.

Returns:

{string,...}

calendar_names ()

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

Returns:

table or nil

lua-calendrica

Contents

Modules

Module calendrica

Usage:

Info:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Raises:

Parameters:

Returns:

Raises:

Parameters:

Returns:

Parameters:

Returns:

Raises:

Parameters:

Returns:

Raises:

Parameters:

Returns:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Module `calendrica`