dng.LiturgiCalcalendar 1.0.2

dng.LiturgiCalcalendar

A lightweight .NET library for calculating the Roman Catholic liturgical calendar.
It provides season detection, season week calculation, psalter cycle (including Roman numerals), and a fast Gregorian Easter implementation. Multilingual season names are supported (DE/EN/FR).

Features

• Gregorian Easter (Meeus/Jones/Butcher) with in-memory cache.
• Season detection for the Roman Rite (Christmas, Lent, Easter, Ordinary Time I & II).
• Season week and Psalter week (including Roman numerals).
• Multilingual season names via simple translation map (DE/EN/FR; fallback to DE).
• .NET 9 support and simple, dependency-free API surface. Types are small and immutable.

Installation

Via NuGet (once published):

dotnet add package dng.LiturgiCalcalendar

Or add the project reference directly during development.

Quick Start

1) Basic calculation

using dng.LiturgiCalcalendar.Roman;
using System.Globalization;

var culture = CultureInfo.GetCultureInfo("en"); // de, en, fr supported
var today   = DateOnly.FromDateTime(DateTime.UtcNow);

var info = RomanRiteCalculator.GetLiturgicalInfo(today, culture);

// Example output
Console.WriteLine($"{info.Date:yyyy-MM-dd} | {info.Weekday} | ISO week {info.IsoWeek}");
Console.WriteLine($"{info.Season} – week {info.SeasonWeek}");
Console.WriteLine($"Psalter week: {info.PsalterWeek} ({info.PsalterWeekRoman})");

GetLiturgicalInfo returns a compact record with all key fields: date, localized weekday, ISO week, season name, season week, psalter week (arabic + Roman).

2) Easter date

var easter2026 = RomanRiteCalculator.GetEaster(2026);

Fast, deterministic calculation using the Meeus/Jones/Butcher algorithm with caching.

3) Multilingual season names

Season IDs are independent from UI texts and can be mapped to language-specific strings:

var (seasonId, start) = RomanRiteCalculator.GetSeason(today);
var seasonName = dng.LiturgiCalcalendar.Roman.RomanRiteSeasonTranslations.Get(seasonId, culture);

Available IDs: Christmas, Lent, Easter, Ordinary1, Ordinary2, Unknown.

4) Roman numerals helper

If you need Roman numerals (e.g., to render psalter week “III”):

var roman = dng.LiturgiCalcalendar.Roman.RomanNumerals.Convert(3); // "III"

Handles the range 1–3999; returns empty string outside that range.

API Overview

• RomanRiteCalculator.GetLiturgicalInfo(DateOnly, CultureInfo?) → LiturgicalInfo
  Single entry point: computes weekday (localized), ISO week, season name, season week, psalter week (arabic + Roman).

• RomanRiteCalculator.GetEaster(int year) → DateOnly
  Gregorian Easter for a given year (cached).

• RomanRiteCalculator.GetSeason(DateOnly) → (RomanRiteSeasonId season, DateOnly start)
  Low-level season calculation (IDs).

• RomanRiteSeasonTranslations.Get(RomanRiteSeasonId, CultureInfo) → string
  Localized season name for DE/EN/FR (fallback to DE).

• RomanNumerals.Convert(int) → string
  Simple, allocation-friendly converter for 1–3999.

• LiturgicalInfo record
  Immutable result DTO: Date, Weekday, IsoWeek, Season, SeasonWeek, PsalterWeek, PsalterWeekRoman.

Notes on season logic

• Lent starts 42 days before Easter (inclusive simplification that covers the Ash week).
• Easter Season runs from Easter Sunday through Pentecost Sunday (Easter + 49).
• Ordinary Time I: Monday after Epiphany through the day before the 43-day Easter offset.
• Ordinary Time II: from the day after Pentecost through the day before the First Sunday of Advent.
• Christmas Season: First Sunday of Advent through the Sunday after Epiphany (Baptism of the Lord).
  These boundaries match the calculator’s current assumptions; local calendars may differ.

Target Frameworks

• .NET 9 (net9.0).
  The code is dependency-free and uses only BCL types.

Development

• Code style/analysis is controlled via .editorconfig and standard analyzers.
• The repo can be built locally or via CI using a Cake script (build.cake) and a GitHub Action that invokes it.
• Typical steps: Restore → Format → Build → Test → Pack → optional Publish.

Testing

Unit tests cover Easter, season boundaries, translations, and Roman numerals. Run locally:

dotnet test

License

MIT – see LICENSE.

Contributing

Contributions, bug reports, and feature requests are welcome.
Please open an issue or pull request on GitHub.

© 2025 Daniel Mueller