calendarium-romanum 0.3.0 → 0.7.1

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

@@ -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 * Temporale::WEEK
+        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?
@@ -19,22 +24,41 @@ module CalendariumRomanum
         end
       end
 
+      # (see .nativity)
       def self.mother_of_god(year)
         octave_of(nativity(year))
       end
 
-      def self.epiphany(year)
-        Date.new(year+1, 1, 6)
+      # @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
 
-      def self.baptism_of_lord(year)
-        sunday_after epiphany(year)
+      # @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 * Temporale::WEEK + 4)
+        easter_sunday(year) - (6 * WEEK + 4)
       end
 
+      # (see .nativity)
       def self.easter_sunday(year)
         year += 1
 
@@ -42,100 +66,157 @@ module CalendariumRomanum
         # https://github.com/jrobertson/easter
 
         golden_number = (year % 19) + 1
-        if year <= 1752 then
-          # Julian calendar
-          dominical_number = (year + (year / 4) + 5) % 7
-          paschal_full_moon = (3 - (11 * golden_number) - 7) % 30
-        else
-          # Gregorian calendar
-          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
-        end
+        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 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
 
-      def self.ascension(year)
+      # (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 * Temporale::WEEK
+        easter_sunday(year) + 7 * WEEK
       end
 
+      # (see .nativity)
       def self.holy_trinity(year)
         octave_of(pentecost(year))
       end
 
-      def self.body_blood(year)
+      # (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)
-        body_blood(year) + 8
+        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 then
-          return date - Temporale::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 + Temporale::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 + Temporale::WEEK
+        if date.wday == weekday
+          date + WEEK
         elsif weekday > date.wday
-          return date + (weekday - date.wday)
+          date + (weekday - date.wday)
         else
-          return date + (Temporale::WEEK - date.wday + weekday)
+          date + (WEEK - date.wday + weekday)
         end
       end
 
+      # @param date [Date]
+      # @return [Date]
       def self.octave_of(date)
-        date + Temporale::WEEK
+        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/extensions/christ_eternal_priest.rb

@@ -1,11 +1,20 @@
 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
-        def self.included(mod)
-          mod.add_celebration(
+        # @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') },
@@ -15,9 +24,12 @@ module CalendariumRomanum
           )
         end
 
-        # method computing date
-        def christ_eternal_priest
-          pentecost + 4
+        # 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

data/lib/calendarium-romanum/transfers.rb

@@ -1,7 +1,22 @@
 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
@@ -28,6 +43,10 @@ module CalendariumRomanum
       end
     end
 
+    # Retrieve solemnity for the specified day
+    #
+    # @param date [Date]
+    # @return [Celebration, nil]
     def get(date)
       @transferred[date]
     end

data/lib/calendarium-romanum/util.rb

@@ -1,12 +1,19 @@
 module CalendariumRomanum
 
+  # General utilities, not tied to the business domain
+  # of liturgical calendar computation.
   module Util
 
     # Abstract superclass for date enumerators.
+    # @abstract
     class DateEnumerator
       include Enumerable
 
+      # @yield [Date]
+      # @return [void, Enumerator]
       def each
+        return to_enum(__method__) unless block_given?
+
         d = @start
         begin
           yield d
@@ -14,14 +21,16 @@ module CalendariumRomanum
         end until enumeration_over? d
       end
 
+      # @param date [Date]
+      # @return [Boolean]
       def enumeration_over?(date)
         @start.send(@prop) != date.send(@prop)
       end
 
-      alias_method :each_day, :each
+      alias each_day each
     end
 
-    # enumerates days of a year
+    # Enumerates days of a year
     class Year < DateEnumerator
       def initialize(year)
         @start = Date.new year, 1, 1
@@ -29,12 +38,36 @@ module CalendariumRomanum
       end
     end
 
-    # enumerates days of a month
+    # Enumerates days of a month
     class Month < DateEnumerator
       def initialize(year, month)
         @start = Date.new year, month, 1
         @prop = :month
       end
     end
+
+    # @api private
+    class DateParser
+      def initialize(date_str)
+        if date_str =~ /((\d{4})(\/|-)?(\d{0,2})(\/|-)?(\d{0,2}))\z/ # Accepts YYYY-MM-DD, YYYY/MM/DD where both day and month are optional
+          year = Regexp.last_match(2).to_i
+          month = Regexp.last_match(4).to_i
+          day = Regexp.last_match(6).to_i
+          @date_range = if (day == 0) && (month == 0) # Only year is given
+                          Year.new(year)
+                        elsif day == 0 # Year and month are given
+                          Month.new(year, month)
+                        else
+                          Date.new(year, month, day)..Date.new(year, month, day)
+                        end
+        else
+          raise ArgumentError, 'Unparseable date'
+        end
+      end
+
+      # @return [DateEnumerator, Range]
+      attr_reader :date_range
+    end
+
   end
 end