calendarium-romanum 0.2.1 → 0.7.0

data/lib/calendarium-romanum/temporale/celebration_factory.rb

@@ -0,0 +1,106 @@
+module CalendariumRomanum
+  class Temporale
+    # Provides factory methods building {Celebration}s
+    # for temporale feasts
+    class CelebrationFactory
+      class << self
+        # @yield [Symbol]
+        # @return [void, Enumerator]
+        def each
+          return to_enum(__method__) unless block_given?
+
+          celebrations.each do |symbol|
+            yield public_send(symbol)
+          end
+        end
+
+        # @return [Celebration]
+        def first_advent_sunday
+          Temporale.create_celebration(
+            I18n.t('temporale.advent.sunday', week: Ordinalizer.ordinal(1)),
+            Ranks::PRIMARY,
+            Colours::VIOLET
+          )
+        end
+
+        private
+
+        def celebrations
+          @celebrations ||= [:first_advent_sunday]
+        end
+
+        def celebration(symbol, rank, colour = Colours::WHITE, fixed_date: false)
+          define_singleton_method(symbol) do
+            Temporale.create_celebration(
+              proc { I18n.t("temporale.solemnity.#{symbol}") },
+              rank,
+              colour,
+              symbol: symbol,
+              date: fixed_date
+            )
+          end
+
+          celebrations << symbol
+        end
+      end
+
+      # @return [Celebration]
+      # @!scope class
+      celebration(:nativity, Ranks::PRIMARY, fixed_date: AbstractDate.new(12, 25))
+      # @return [Celebration]
+      # @!scope class
+      celebration(:holy_family, Ranks::FEAST_LORD_GENERAL)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:mother_of_god, Ranks::SOLEMNITY_GENERAL, fixed_date: AbstractDate.new(1, 1))
+      # @return [Celebration]
+      # @!scope class
+      celebration(:epiphany, Ranks::PRIMARY)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:baptism_of_lord, Ranks::FEAST_LORD_GENERAL)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:ash_wednesday, Ranks::PRIMARY, Colours::VIOLET)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:good_friday, Ranks::TRIDUUM, Colours::RED)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:holy_saturday, Ranks::TRIDUUM, Colours::VIOLET)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:palm_sunday, Ranks::PRIMARY, Colours::RED)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:easter_sunday, Ranks::TRIDUUM)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:ascension, Ranks::PRIMARY)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:pentecost, Ranks::PRIMARY, Colours::RED)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:holy_trinity, Ranks::SOLEMNITY_GENERAL)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:corpus_christi, Ranks::SOLEMNITY_GENERAL)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:sacred_heart, Ranks::SOLEMNITY_GENERAL)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:christ_king, Ranks::SOLEMNITY_GENERAL)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:mother_of_church, Ranks::MEMORIAL_GENERAL)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:immaculate_heart, Ranks::MEMORIAL_GENERAL)
+      # @return [Celebration]
+      # @!scope class
+      celebration(:saturday_memorial_bvm, Ranks::MEMORIAL_OPTIONAL)
+    end
+  end
+end

data/lib/calendarium-romanum/temporale/dates.rb

@@ -0,0 +1,232 @@
+module CalendariumRomanum
+  class Temporale
+    # Provides methods computing dates of movable feasts
+    # and utilities for common computations of relative dates
+    module Dates
+      # (see .nativity)
+      def self.first_advent_sunday(year)
+        sunday_before(nativity(year)) - 3 * WEEK
+      end
+
+      # @param year [Fixnum] liturgical year
+      # @return [Date]
+      def self.nativity(year)
+        Date.new(year, 12, 25)
+      end
+
+      # (see .nativity)
+      def self.holy_family(year)
+        xmas = nativity(year)
+        if xmas.sunday?
+          return Date.new(year, 12, 30)
+        else
+          sunday_after(xmas)
+        end
+      end
+
+      # (see .nativity)
+      def self.mother_of_god(year)
+        octave_of(nativity(year))
+      end
+
+      # @param year [Fixnum] liturgical year
+      # @param sunday [Boolean] transfer to Sunday?
+      # @return [Date]
+      def self.epiphany(year, sunday: false)
+        if sunday
+          # GNLYC 7 a)
+          return sunday_after(Date.new(year + 1, 1, 1))
+        end
+
+        Date.new(year + 1, 1, 6)
+      end
+
+      # @param year [Fixnum] liturgical year
+      # @param epiphany_on_sunday [Boolean] was Epiphany transferred to Sunday?
+      # @return [Date]
+      def self.baptism_of_lord(year, epiphany_on_sunday: false)
+        e = epiphany(year, sunday: epiphany_on_sunday)
+        if epiphany_on_sunday
+          e + 1
+        else
+          sunday_after e
+        end
+      end
+
+      # (see .nativity)
+      def self.ash_wednesday(year)
+        easter_sunday(year) - (6 * WEEK + 4)
+      end
+
+      # (see .nativity)
+      def self.easter_sunday(year)
+        year += 1
+
+        # algorithm below taken from the 'easter' gem:
+        # https://github.com/jrobertson/easter
+
+        golden_number = (year % 19) + 1
+        dominical_number = (year + (year / 4) - (year / 100) + (year / 400)) % 7
+        solar_correction = (year - 1600) / 100 - (year - 1600) / 400
+        lunar_correction = (((year - 1400) / 100) * 8) / 25
+        paschal_full_moon = (3 - 11 * golden_number + solar_correction - lunar_correction) % 30
+        dominical_number += 7 until dominical_number > 0
+        paschal_full_moon += 30 until paschal_full_moon > 0
+        paschal_full_moon -= 1 if (paschal_full_moon == 29) || ((paschal_full_moon == 28) && golden_number > 11)
+        difference = (4 - paschal_full_moon - dominical_number) % 7
+        difference += 7 if difference < 0
+        day_easter = paschal_full_moon + difference + 1
+        if day_easter < 11
+          # Easter occurs in March.
+          return Date.new(year, 3, day_easter + 21)
+        else
+          # Easter occurs in April.
+          return Date.new(year, 4, day_easter - 10)
+        end
+      end
+
+      # (see .nativity)
+      def self.palm_sunday(year)
+        easter_sunday(year) - 7
+      end
+
+      # (see .nativity)
+      def self.good_friday(year)
+        easter_sunday(year) - 2
+      end
+
+      # (see .nativity)
+      def self.holy_saturday(year)
+        easter_sunday(year) - 1
+      end
+
+      # (see .epiphany)
+      def self.ascension(year, sunday: false)
+        if sunday
+          # GNLYC 7 b)
+          return easter_sunday(year) + 6 * WEEK
+        end
+
+        pentecost(year) - 10
+      end
+
+      # (see .nativity)
+      def self.pentecost(year)
+        easter_sunday(year) + 7 * WEEK
+      end
+
+      # (see .nativity)
+      def self.holy_trinity(year)
+        octave_of(pentecost(year))
+      end
+
+      # (see .epiphany)
+      def self.corpus_christi(year, sunday: false)
+        if sunday
+          # GNLYC 7 c)
+          return holy_trinity(year) + WEEK
+        end
+
+        holy_trinity(year) + 4
+      end
+
+      # (see .nativity)
+      def self.sacred_heart(year)
+        corpus_christi(year) + 8
+      end
+
+      # (see .nativity)
+      def self.mother_of_church(year)
+        pentecost(year) + 1
+      end
+
+      # (see .nativity)
+      def self.immaculate_heart(year)
+        pentecost(year) + 20
+      end
+
+      # (see .nativity)
+      def self.christ_king(year)
+        first_advent_sunday(year + 1) - 7
+      end
+
+      # utility methods
+
+      # @param weekday [Fixnum]
+      # @param date [Date]
+      # @return [Date]
+      def self.weekday_before(weekday, date)
+        if date.wday == weekday
+          date - WEEK
+        elsif weekday < date.wday
+          date - (date.wday - weekday)
+        else
+          date - (date.wday + WEEK - weekday)
+        end
+      end
+
+      # (see .weekday_before)
+      def self.weekday_after(weekday, date)
+        if date.wday == weekday
+          date + WEEK
+        elsif weekday > date.wday
+          date + (weekday - date.wday)
+        else
+          date + (WEEK - date.wday + weekday)
+        end
+      end
+
+      # @param date [Date]
+      # @return [Date]
+      def self.octave_of(date)
+        date + WEEK
+      end
+
+      class << self
+        # @!method sunday_before(date)
+        #   @param date [Date]
+        #   @return [Date]
+        # @!method monday_before(date)
+        #   (see .sunday_before)
+        # @!method tuesday_before(date)
+        #   (see .sunday_before)
+        # @!method wednesday_before(date)
+        #   (see .sunday_before)
+        # @!method thursday_before(date)
+        #   (see .sunday_before)
+        # @!method friday_before(date)
+        #   (see .sunday_before)
+        # @!method saturday_before(date)
+        #   (see .sunday_before)
+
+        # @!method sunday_after(date)
+        #   @param date [Date]
+        #   @return [Date]
+        # @!method monday_after(date)
+        #   (see .sunday_after)
+        # @!method tuesday_after(date)
+        #   (see .sunday_after)
+        # @!method wednesday_after(date)
+        #   (see .sunday_after)
+        # @!method thursday_after(date)
+        #   (see .sunday_after)
+        # @!method friday_after(date)
+        #   (see .sunday_after)
+        # @!method saturday_after(date)
+        #   (see .sunday_after)
+
+        # @api private
+        WEEKDAYS = %w(sunday monday tuesday wednesday thursday friday saturday).freeze
+        WEEKDAYS.each_with_index do |weekday, weekday_i|
+          define_method "#{weekday}_before" do |date|
+            send('weekday_before', weekday_i, date)
+          end
+
+          define_method "#{weekday}_after" do |date|
+            send('weekday_after', weekday_i, date)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/calendarium-romanum/temporale/extensions/christ_eternal_priest.rb

@@ -0,0 +1,37 @@
+module CalendariumRomanum
+  class Temporale
+    module Extensions
+      # {Temporale} extension adding the movable feast
+      # of "Christ Eternal Priests",
+      # included in some local calendars
+      #
+      # @example
+      #   temporale = Temporale.new(2015, extensions: [
+      #     Temporale::Extensions::ChristEternalPriest
+      #   ])
+      module ChristEternalPriest
+        # @yield [Symbol, Celebration]
+        # @return [void]
+        def self.each_celebration
+          yield(
+            # symbol refers to the date-computing method
+            :christ_eternal_priest,
+            Celebration.new(
+              proc { I18n.t('temporale.extension.christ_eternal_priest') },
+              Ranks::FEAST_PROPER,
+              Colours::WHITE
+            )
+          )
+        end
+
+        # Computes the feast's date
+        #
+        # @param year [Fixnum] liturgical year
+        # @return [Date]
+        def self.christ_eternal_priest(year)
+          Dates.pentecost(year) + 4
+        end
+      end
+    end
+  end
+end

data/lib/calendarium-romanum/transfers.rb

@@ -1,12 +1,29 @@
 module CalendariumRomanum
 
-  # Resolves transfers of solemnities.
+  # Internal {Calendar} component.
+  # Resolves transfers of conflicting solemnities.
+  #
+  # For any day {Temporale} has a {Celebration}.
+  # Often {Sanctorale} has one (or more), too.
+  # {Calendar} handles these conflicts, in most cases
+  # by throwing away all the proposed {Celebration}s except
+  # of the one of highest rank.
+  # But when there are two conflicting _solemnities_,
+  # one is celebrated on the given day and the less lucky one
+  # must be transferred to another day.
+  # However, not all days are valid as targets of solemnity transfer.
+  #
+  # @api private
   class Transfers
+    # @param temporale [Temporale]
+    # @param sanctorale [Sanctorale]
     def initialize(temporale, sanctorale)
       @transferred = {}
+      @temporale = temporale
+      @sanctorale = sanctorale
 
       dates = sanctorale.solemnities.keys.collect do |abstract_date|
-        temporale.concretize_abstract_date abstract_date
+        concretize_abstract_date abstract_date
       end.sort
 
       dates.each do |date|
@@ -21,24 +38,44 @@ module CalendariumRomanum
         transfer_to = date
         begin
           transfer_to = transfer_to.succ
-        end until valid_destination?(transfer_to, temporale, sanctorale)
+        end until valid_destination?(transfer_to)
         @transferred[transfer_to] = loser
       end
     end
 
+    # Retrieve solemnity for the specified day
+    #
+    # @param date [Date]
+    # @return [Celebration, nil]
     def get(date)
       @transferred[date]
     end
 
     private
 
-    def valid_destination?(day, temporale, sanctorale)
-      return false if temporale.get(day).rank >= Ranks::FEAST_PROPER
+    def valid_destination?(day)
+      return false if @temporale.get(day).rank >= Ranks::FEAST_PROPER
 
-      sc = sanctorale.get(day)
+      sc = @sanctorale.get(day)
       return false if sc.size > 0 && sc.first.rank >= Ranks::FEAST_PROPER
 
       true
     end
+
+    # Converts an AbstractDate to a Date in the given
+    # liturgical year.
+    # It isn't guaranteed to work well (and probably doesn't work well)
+    # for the grey zone of dates between earliest and latest
+    # possible date of the first Advent Sunday, but that's no problem
+    # as long as there are no sanctorale solemnities in this
+    # date range.
+    def concretize_abstract_date(abstract_date)
+      d = abstract_date.concretize(@temporale.year + 1)
+      if @temporale.date_range.include? d
+        d
+      else
+        abstract_date.concretize(@temporale.year)
+      end
+    end
   end
 end