calendarium-romanum

Ruby gem for calendar computations according to the Roman Catholic liturgical calendar as instituted by MP Paschalis[http://w2.vatican.va/content/paul-vi/en/motu_proprio/documents/hf_p-vi_motu-proprio_19690214_mysterii-paschalis.html] of Paul VI. (AAS 61 (1969), pp. 222-226). The rules are defined in Norms for the Liturgical Year and the Calendar[https://www.ewtn.com/catholicism/library/liturgical-year-2193].

Quickstart

For usage instructions with copy-pastable code examples see README

Object model overview

Calendar is the library’s main functional unit. It represents calendar for a single liturgical year and allows retrieving calendar data for any of the year’s days. Calendar basically consists of a Temporale and a Sanctorale and it’s main task is to combine information from both and for any day of the year produce a fully and correctly populated Day instance, containing one or more Celebrations (see Calendar#[]).

(Calendar does not own either Temporale or Sanctorale - it is possible to pass them on initialization and they are treated as read-only. The only exception is method #freeze, which freezes all the Calendar‘s contents, including Temporale and Sanctorale.)

PerpetualCalendar is a higher-level API for retrieving calendar data without bothering about liturgical years. It builds Calendar instances internally and passes method calls to them.

Day contains complete calendar data of a liturgical day. It owns one or more Celebrations. If there are multiple it means that any one of them can be chosen and celebrated that day.

Celebration represents a celebration (particular solemnity / feast / memorial / Sunday / ferial) and holds it’s liturgical properties, encoded mostly by value objects.

(Unlike Day, Celebration instances are not bound to a particular date, they represent “celebration C in general”, not “celebration C in year Y”. The latter is represented only by a combination of Celebration and Day. Celebration instances are immutable and some may be used repeatedly in context of various days and calendars.)

Season, Rank, Colour are value objects representing values of Celebration properties. Immutable instances representing the standard values are referenced by constants and normally there should be no need to create any more.

Temporale represents the temporale cycle of a single liturgical year, computes movable feasts, determines liturgical seasons. For any day of the year it provides a temporale Celebration.

Sanctorale represents the sanctorale cycle, i.e. the fixed-date celebrations, mostly feasts of saints. It is not bound to a particular year, hence a single instance can be used by many Calendar instances representing various liturgical years. For any day it provides zero or more Celebrations.

Most particular calendars (calendars of countries, provinces, dioceses, churches, religious institutes) share the same temporale definition and differ in sanctorale contents. Therefore the task of implementing a particular calendar usually consists of populating a Sanctorale instance with the desired data. A convenient way to do so is preparing a sanctorale data file and loading it using SanctoraleLoader.