calendarium-romanum 0.5.0 → 0.9.0

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

@@ -1,10 +1,22 @@
 module CalendariumRomanum
   class Temporale
-    # builds temporale Celebrations
+    # 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
-          Celebration.new(
+          Temporale.create_celebration(
             I18n.t('temporale.advent.sunday', week: Ordinalizer.ordinal(1)),
             Ranks::PRIMARY,
             Colours::VIOLET
@@ -13,36 +25,83 @@ module CalendariumRomanum
 
         private
 
-        def celebration(symbol, rank, colour = Colours::WHITE)
+        def celebrations
+          @celebrations ||= [:first_advent_sunday]
+        end
+
+        def celebration(symbol, rank, colour = Colours::WHITE, fixed_date: nil, sunday: nil)
           define_singleton_method(symbol) do
-            Celebration.new(
+            Temporale.create_celebration(
               proc { I18n.t("temporale.solemnity.#{symbol}") },
               rank,
               colour,
-              symbol
+              symbol: symbol,
+              date: fixed_date,
+              sunday: sunday
             )
           end
+
+          celebrations << symbol
         end
       end
 
-      # define factory methods
-      celebration(:nativity, Ranks::PRIMARY)
+      # @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)
-      celebration(:mother_of_god, Ranks::SOLEMNITY_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)
-      celebration(:palm_sunday, Ranks::PRIMARY, Colours::RED)
+      # @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/date_helper.rb

@@ -0,0 +1,85 @@
+module CalendariumRomanum
+  class Temporale
+    # Provides utility methods for date arithmetics, available
+    # both as mixin instance methods and module methods.
+    #
+    # @since 0.9.0
+    module DateHelper
+      extend self
+
+      # @param weekday [Integer]
+      # @param date [Date]
+      # @return [Date]
+      def 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 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 octave_of(date)
+        date + WEEK
+      end
+
+      # @!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

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

@@ -1,16 +1,24 @@
 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
-      def self.first_advent_sunday(year)
+      include DateHelper
+      extend self
+
+      # (see #nativity)
+      def first_advent_sunday(year)
         sunday_before(nativity(year)) - 3 * WEEK
       end
 
-      def self.nativity(year)
+      # @param year [Integer] liturgical year
+      # @return [Date]
+      def nativity(year)
         Date.new(year, 12, 25)
       end
 
-      def self.holy_family(year)
+      # (see #nativity)
+      def holy_family(year)
         xmas = nativity(year)
         if xmas.sunday?
           return Date.new(year, 12, 30)
@@ -19,11 +27,15 @@ module CalendariumRomanum
         end
       end
 
-      def self.mother_of_god(year)
+      # (see #nativity)
+      def mother_of_god(year)
         octave_of(nativity(year))
       end
 
-      def self.epiphany(year, sunday: false)
+      # @param year [Integer] liturgical year
+      # @param sunday [Boolean] transfer to Sunday?
+      # @return [Date]
+      def epiphany(year, sunday: false)
         if sunday
           # GNLYC 7 a)
           return sunday_after(Date.new(year + 1, 1, 1))
@@ -32,20 +44,25 @@ module CalendariumRomanum
         Date.new(year + 1, 1, 6)
       end
 
-      def self.baptism_of_lord(year, epiphany_on_sunday: false)
+      # @param year [Integer] liturgical year
+      # @param epiphany_on_sunday [Boolean] was Epiphany transferred to Sunday?
+      # @return [Date]
+      def 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
 
-      def self.ash_wednesday(year)
+      # (see #nativity)
+      def ash_wednesday(year)
         easter_sunday(year) - (6 * WEEK + 4)
       end
 
-      def self.easter_sunday(year)
+      # (see #nativity)
+      def easter_sunday(year)
         year += 1
 
         # algorithm below taken from the 'easter' gem:
@@ -71,19 +88,23 @@ module CalendariumRomanum
         end
       end
 
-      def self.palm_sunday(year)
+      # (see #nativity)
+      def palm_sunday(year)
         easter_sunday(year) - 7
       end
 
-      def self.good_friday(year)
+      # (see #nativity)
+      def good_friday(year)
         easter_sunday(year) - 2
       end
 
-      def self.holy_saturday(year)
+      # (see #nativity)
+      def holy_saturday(year)
         easter_sunday(year) - 1
       end
 
-      def self.ascension(year, sunday: false)
+      # (see .epiphany)
+      def ascension(year, sunday: false)
         if sunday
           # GNLYC 7 b)
           return easter_sunday(year) + 6 * WEEK
@@ -92,15 +113,18 @@ module CalendariumRomanum
         pentecost(year) - 10
       end
 
-      def self.pentecost(year)
+      # (see #nativity)
+      def pentecost(year)
         easter_sunday(year) + 7 * WEEK
       end
 
-      def self.holy_trinity(year)
+      # (see #nativity)
+      def holy_trinity(year)
         octave_of(pentecost(year))
       end
 
-      def self.corpus_christi(year, sunday: false)
+      # (see .epiphany)
+      def corpus_christi(year, sunday: false)
         if sunday
           # GNLYC 7 c)
           return holy_trinity(year) + WEEK
@@ -109,55 +133,24 @@ module CalendariumRomanum
         holy_trinity(year) + 4
       end
 
-      def self.sacred_heart(year)
+      # (see #nativity)
+      def sacred_heart(year)
         corpus_christi(year) + 8
       end
 
-      def self.immaculate_heart(year)
-        pentecost(year) + 20
-      end
-
-      def self.christ_king(year)
-        first_advent_sunday(year + 1) - 7
-      end
-
-      # utility methods
-
-      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
-
-      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
+      # (see #nativity)
+      def mother_of_church(year)
+        pentecost(year) + 1
       end
 
-      def self.octave_of(date)
-        date + WEEK
+      # (see #nativity)
+      def immaculate_heart(year)
+        pentecost(year) + 20
       end
 
-      class << self
-        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
+      # (see #nativity)
+      def christ_king(year)
+        first_advent_sunday(year + 1) - 7
       end
     end
   end

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