Romcal

A Rust library for calculating Catholic liturgical dates and generating liturgical calendars.

For command-line usage, see the CLI documentation.

Installation

Add to your Cargo.toml:

[dependencies]
romcal = "4.0"

Quick Start

use romcal::Romcal;

fn main() -> romcal::RomcalResult<()> {
    // Create a default configuration
    let romcal = Romcal::default();

    // Get a specific liturgical date
    let easter = romcal.get_date("easter_sunday", 2026)?;
    println!("Easter 2026: {}", easter);  // 2026-04-05

    // Generate the liturgical calendar for year 2026
    let calendar = romcal.generate_liturgical_calendar(2026)?;

    // Access a specific date
    if let Some(days) = calendar.get("2025-12-25") {
        for day in days {
            println!("{}: {}", day.date, day.fullname);
        }
    }

    Ok(())
}

Configuration

Using Preset

Preset is a configuration builder with optional fields. Use Romcal::new(preset) to create an instance:

use romcal::{Preset, Romcal, CalendarContext, EasterCalculationType};

let preset = Preset {
    calendar: Some("france".to_string()),
    locale: Some("fr".to_string()),
    context: Some(CalendarContext::Liturgical),
    epiphany_on_sunday: Some(true),
    ascension_on_sunday: Some(true),
    corpus_christi_on_sunday: Some(true),
    ..Preset::default()
};

let romcal = Romcal::new(preset);

Configuration Options

Available Calendars and Locales

use romcal::{CALENDAR_IDS, LOCALE_CODES};

// List all available calendar IDs
for id in CALENDAR_IDS {
    println!("{}", id);
}

// List all available locale codes
for code in LOCALE_CODES {
    println!("{}", code);
}

Loading Calendar Data

For calendar generation, you need to load calendar definitions and resources:

use romcal::{Preset, Romcal};

// Load from JSON files or embedded data
let calendar_definitions = load_calendar_definitions(); // Your loading logic
let resources = load_resources();                       // Your loading logic

let preset = Preset {
    calendar: Some("france".to_string()),
    locale: Some("fr".to_string()),
    calendar_definitions: Some(calendar_definitions),
    resources: Some(resources),
    ..Preset::default()
};

let romcal = Romcal::new(preset);

Getting a Liturgical Date by ID

The get_date method calculates a liturgical date by its ID:

use romcal::Romcal;

let romcal = Romcal::default();

// Easter-related dates
let easter = romcal.get_date("easter_sunday", 2026)?;       // 2026-04-05
let ash_wed = romcal.get_date("ash_wednesday", 2026)?;      // 2026-02-18
let pentecost = romcal.get_date("pentecost_sunday", 2026)?; // 2026-05-24

// Fixed feasts
let christmas = romcal.get_date("christmas", 2026)?;        // 2026-12-25
let all_saints = romcal.get_date("all_saints", 2026)?;      // 2026-11-01

// Any date from the calendar
let monday = romcal.get_date("ordinary_time_5_monday", 2026)?;

Any date ID from the liturgical calendar can be used (e.g., easter_sunday, christmas, ordinary_time_5_monday).

Generating a Liturgical Calendar

Generate a complete liturgical calendar with all celebrations:

use romcal::Romcal;

let romcal = Romcal::default();

// Year parameter is the liturgical year end (2026 = liturgical year 2025-2026)
let calendar = romcal.generate_liturgical_calendar(2026)?;

// calendar is BTreeMap<String, Vec<LiturgicalDay>>
// Keys are dates in "YYYY-MM-DD" format
for (date, days) in &calendar {
    for day in days {
        println!("{}: {} ({:?})", date, day.fullname, day.rank);
    }
}

LiturgicalDay Structure

Each LiturgicalDay contains:

Generating a Mass-Centric Calendar

The mass-centric calendar organizes by civil date and mass time, useful for scheduling:

use romcal::Romcal;

let romcal = Romcal::default();
let mass_calendar = romcal.generate_mass_calendar(2026)?;

// mass_calendar is BTreeMap<String, Vec<MassContext>>
// Keys are civil dates (not liturgical dates)
for (civil_date, masses) in &mass_calendar {
    for mass in masses {
        println!("{} - {:?}: {} (liturgical: {})",
            mass.civil_date,
            mass.mass_time,
            mass.fullname,
            mass.liturgical_date
        );
    }
}

Key Difference from Liturgical Calendar

Evening masses appear on the previous civil day:

• Easter Vigil (April 19) has civil_date: "2025-04-19" but liturgical_date: "2025-04-20"
• Christmas Vigil Mass has civil_date: "2025-12-24" but liturgical_date: "2025-12-25"

MassContext Structure

Each MassContext is a flat structure containing:

Creating an Optimized Bundle

Generate a minimal JSON bundle for deployment (useful for web/mobile apps):

use romcal::{Preset, Romcal};

let preset = Preset {
    calendar: Some("france".to_string()),
    locale: Some("fr".to_string()),
    calendar_definitions: Some(all_definitions),
    resources: Some(all_resources),
    ..Preset::default()
};

let romcal = Romcal::new(preset);
let json_bundle = romcal.optimize()?;

// json_bundle contains only:
// - Target calendar and its parent calendars
// - Target locale and parent locales
// - Entities actually used in the calendar

Key Types

Seasons

The liturgical year is divided into five seasons:

Ranks

Celebrations are classified by rank, from highest to lowest (GNLY #11-16):

Precedence

Precedence levels are essential for determining which celebration takes priority when multiple celebrations fall on the same day. Romcal implements the 13 levels defined in the General Norms for the Liturgical Year and the Calendar (GNLY #49):

Liturgical Colors

Colors are automatically computed based on the season and celebration. For memorials of martyrs, red is automatically applied.

Liturgical Periods

Periods are sub-divisions within liturgical seasons, traditionally used in monastic and religious communities. They help determine specific elements such as the antiphon to the Blessed Virgin Mary (Alma Redemptoris Mater, Ave Regina Caelorum, Regina Caeli, Salve Regina).

Cycles

Cycles determine which readings and psalms are used in the liturgy.

Sunday Cycle (SundayCycle): A three-year cycle for Sunday and solemnity readings.

Weekday Cycle (WeekdayCycle): A two-year cycle for weekday readings (first reading only; Gospel follows its own sequence).

Psalter Week (PsalterWeekCycle): A four-week cycle for the Liturgy of the Hours (Divine Office).

Mass Times

MassTime variants:

Error Handling

All fallible operations return RomcalResult<T>, which is an alias for Result<T, RomcalError>.

use romcal::{Romcal, RomcalResult, RomcalError};

fn generate_calendar() -> RomcalResult<()> {
    let romcal = Romcal::default();

    // This will fail: year must be >= 1583 (Gregorian calendar adoption)
    match romcal.generate_liturgical_calendar(1500) {
        Ok(calendar) => { /* use calendar */ }
        Err(RomcalError::InvalidYear(year, min_year)) => {
            eprintln!("Invalid year: {} (min: {})", year, min_year);
        }
        Err(e) => {
            eprintln!("Error: {}", e);
        }
    }

    Ok(())
}

Error Types

Development

# Run tests
cargo test -p romcal

# Run quality checks
./scripts/check-core.sh

# Build release
cargo build -p romcal --release

Related

• romcal - Main Romcal project
• romcal-cli - Command-line interface
• romcal (TypeScript) - TypeScript/JavaScript binding
• romcal (Python) - Python binding

License

Apache License 2.0. See LICENSE for details.