calendarium-romanum 0.4.0 → 0.8.0

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

@@ -0,0 +1,107 @@
+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: nil, sunday: nil)
+          define_singleton_method(symbol) do
+            Temporale.create_celebration(
+              proc { I18n.t("temporale.solemnity.#{symbol}") },
+              rank,
+              colour,
+              symbol: symbol,
+              date: fixed_date,
+              sunday: sunday
+            )
+          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, sunday: true)
+      # @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

@@ -1,15 +1,20 @@
 module CalendariumRomanum
   class Temporale
-    # dates of movable feasts
+    # 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 [Integer] 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?
@@ -19,32 +24,41 @@ module CalendariumRomanum
         end
       end
 
+      # (see .nativity)
       def self.mother_of_god(year)
         octave_of(nativity(year))
       end
 
+      # @param year [Integer] 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)
+        Date.new(year + 1, 1, 6)
       end
 
+      # @param year [Integer] 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
+        if e.day > 6
           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
 
@@ -58,31 +72,35 @@ module CalendariumRomanum
         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 or (paschal_full_moon == 28 and golden_number > 11)
+        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 then
+        if day_easter < 11
           # Easter occurs in March.
-          return Date.new(y=year, m=3, d=day_easter + 21)
+          return Date.new(year, 3, day_easter + 21)
         else
           # Easter occurs in April.
-          return Date.new(y=year, m=4, d=day_easter - 10)
+          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)
@@ -92,14 +110,17 @@ module CalendariumRomanum
         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)
@@ -109,46 +130,93 @@ module CalendariumRomanum
         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 [Integer]
+      # @param date [Date]
+      # @return [Date]
       def self.weekday_before(weekday, date)
-        if date.wday == weekday then
-          return date - WEEK
+        if date.wday == weekday
+          date - WEEK
         elsif weekday < date.wday
-          return date - (date.wday - weekday)
+          date - (date.wday - weekday)
         else
-          return date - (date.wday + WEEK - weekday)
+          date - (date.wday + WEEK - weekday)
         end
       end
 
+      # (see .weekday_before)
       def self.weekday_after(weekday, date)
-        if date.wday == weekday then
-          return date + WEEK
+        if date.wday == weekday
+          date + WEEK
         elsif weekday > date.wday
-          return date + (weekday - date.wday)
+          date + (weekday - date.wday)
         else
-          return date + (WEEK - date.wday + weekday)
+          date + (WEEK - date.wday + weekday)
         end
       end
 
+      # @param date [Date]
+      # @return [Date]
       def self.octave_of(date)
         date + WEEK
       end
 
       class << self
-        WEEKDAYS = %w{sunday monday tuesday wednesday thursday friday saturday}
+        # @!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)

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

@@ -0,0 +1,27 @@
+module CalendariumRomanum
+  class Temporale
+    # @since 0.8.0
+    class EasterTable
+      # Loads an Easter table from a String- or IO-like object +src+.
+      # +src+ must contain Easter dates, parseable by +Date.parse+, one date per line.
+      # Blank lines and bash-like comments are ignored.
+      # Returns a +Hash+ mapping (liturgical) year to Easter date.
+      #
+      # @param src [#each_line]
+      # @return [Hash<Integer=>Date>]
+      def self.load_from(src)
+        r = {}
+        src.each_line do |l|
+          cleaned = l.sub(/#.*$/, '').strip
+          next if cleaned == ''
+
+          date = Date.parse cleaned
+          liturgical_year = date.year - 1
+          r[liturgical_year] = date
+        end
+
+        r
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module CalendariumRomanum
+  class Temporale
+    module Extensions
+      # Returns all Temporale extensions defined by the gem.
+      #
+      # @return [Array<Module>]
+      # @since 0.8.0
+      def self.all
+        constants
+          .collect {|c| const_get(c) }
+          .select {|c| c.is_a? Module }
+      end
+    end
+  end
+end

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

@@ -1,21 +1,34 @@
 module CalendariumRomanum
   class Temporale
     module Extensions
-      # Temporale extension adding feast of Christ Eternal Priests,
+      # {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
+              Colours::WHITE,
+              :christ_eternal_priest
             )
           )
         end
 
-        # method computing date
+        # Computes the feast's date
+        #
+        # @param year [Integer] liturgical year
+        # @return [Date]
         def self.christ_eternal_priest(year)
           Dates.pentecost(year) + 4
         end

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

@@ -0,0 +1,73 @@
+module CalendariumRomanum
+  class Temporale
+    module Extensions
+      # {Temporale} extension adding solemnity of dedication
+      # of a church celebrated on the Sunday before All Saints /
+      # last October Sunday.
+      #
+      # In churches, whose actual day of consecration is unknown, the anniversary
+      # of consecration is celebrated either on October 25th, or on the Sunday
+      # before All Saints (cf. Notitiae 71/1972, p. 103).
+      # This extension implements the latter case.
+      #
+      # @example
+      #   # It can be used either this way
+      #   temporale = Temporale.new(2015, extensions: [
+      #     Temporale::Extensions::DedicationBeforeAllSaints
+      #   ])
+      #
+      #   # Or, if you want to customize celebration title and/or symbol:
+      #   temporale = Temporale.new(2015, extensions: [
+      #     Temporale::Extensions::DedicationBeforeAllSaints.new(title: 'Title', symbol: :symbol)
+      #   ])
+      #
+      # @since 0.8.0
+      class DedicationBeforeAllSaints
+        DEFAULT_TITLE = proc { I18n.t('temporale.extension.dedication') }
+        DEFAULT_SYMBOL = :dedication
+
+        # @yield [Symbol, Celebration]
+        # @return [void]
+        def self.each_celebration
+          yield(
+            # symbol refers to the date-computing method
+            :dedication,
+            Celebration.new(
+              DEFAULT_TITLE,
+              Ranks::SOLEMNITY_PROPER,
+              Colours::WHITE,
+              DEFAULT_SYMBOL
+            )
+          )
+        end
+
+        # Computes date of the solemnity
+        #
+        # @param year [Integer] liturgical year
+        # @return [Date]
+        def self.dedication(year)
+          Dates.sunday_before(Date.new(year + 1, 11, 1))
+        end
+
+        def initialize(title: DEFAULT_TITLE, symbol: DEFAULT_SYMBOL)
+          @title = title
+          @symbol = symbol
+        end
+
+        # @yield [Symbol, Celebration]
+        # @return [void]
+        def each_celebration
+          yield(
+            proc {|year| self.class.dedication(year) },
+            Celebration.new(
+              @title,
+              Ranks::SOLEMNITY_PROPER,
+              Colours::WHITE,
+              @symbol
+            )
+          )
+        end
+      end
+    end
+  end
+end