lua-calendrica

Lua port of the calendrical algorithms from Calendrical Calculations (4th edition) by Nachum Dershowitz and Edward M. Reingold.

Covers a wide range of calendars including Gregorian, Hebrew, Islamic, Persian, Chinese, Hindu (modern and old), Tibetan, Balinese, Mayan, Julian, Coptic, Ethiopic, French Revolutionary, Icelandic, Akan, Bahá'í, and more, along with astronomical calculations for sunrise, sunset, lunar phases, and solar terms.

Requirements

• Lua 5.3 or later

Usage

High-level API

local calendrica = require("calendrica")

-- Create a date on one calendar and convert to another
local d = calendrica.new_date({year=2024, month=1, day=1}, calendrica.cal_gregorian)
local h = calendrica.as_date(d, calendrica.cal_hebrew)
print(h.year, h.month, h.day)

-- Look up holidays
local dates = calendrica.holiday("shavuot", 2026)
print(dates[1])  -- fixed date (Rata Die)

Low-level API

Each calendar is also available as a standalone module:

local gregorian = require("calendrica-gregorian")
local hebrew    = require("calendrica-hebrew")

local fixed = gregorian.fixed_from_gregorian({2024, 1, 1})
local h     = hebrew.hebrew_from_fixed(fixed)
print(h[1], h[2], h[3])  -- year, month, day

The standalone modules sometimes have more functionality, such as leap year predicate.

Modules

Documentation

API documentation is available at https://polyglossia.codeberg.page/lua-calendrica/

License

The algorithms are ported from CALENDRICA 4.0, which is licensed under the Apache License 2.0. See the source files for details.