# lua-calendrica

Lua port of the calendrical algorithms from
[Calendrical Calculations (4th edition)](https://www.cambridge.org/9781107683167)
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

```lua
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:

```lua
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

| Module | Description |
|--------|-------------|
| `calendrica` | High-level API: date objects, calendar conversion, holiday registry |
| `calendrica-basic` | Core arithmetic and utility functions |
| `calendrica-astro` | Astronomical calculations (solar, lunar, location) |
| `calendrica-gregorian` | Gregorian calendar |
| `calendrica-julian` | Julian calendar and Roman dates |
| `calendrica-hebrew` | Hebrew calendar |
| `calendrica-islamic` | Arithmetic and observational Islamic calendars |
| `calendrica-persian` | Astronomical and arithmetic Persian calendars |
| `calendrica-chinese` | Chinese, Japanese, Korean, and Vietnamese calendars |
| `calendrica-modern-hindu` | Modern Hindu solar and lunar calendars |
| `calendrica-old-hindu` | Old Hindu solar and lunar calendars |
| `calendrica-tibetan` | Tibetan calendar |
| `calendrica-bahai` | Bahá'í calendar (arithmetic and astronomical) |
| `calendrica-balinese` | Balinese Pawukon calendar |
| `calendrica-mayan` | Mayan and Aztec calendars |
| `calendrica-coptic-ethiopic` | Coptic and Ethiopic calendars |
| `calendrica-ecclesiastical` | Easter and Christian holidays |
| `calendrica-iso` | ISO week calendar |
| `calendrica-french-revolutionary` | French Revolutionary calendar |
| `calendrica-egyptian-armenian` | Egyptian and Armenian calendars |
| `calendrica-icelandic` | Icelandic calendar |
| `calendrica-akan` | Akan day-name calendar |
| `calendrica-astronomical-lunar` | Observational lunar calendars (Babylonian, Samaritan, observational Islamic and Hebrew) |

## 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.