calendarium-romanum 0.3.0 → 0.7.1

data/lib/calendarium-romanum/temporale.rb

@@ -2,28 +2,44 @@ require 'date'
 
 module CalendariumRomanum
 
-  # determine seasons and dates of the Temporale feasts of the given year
+  # One of the two main {Calendar} components.
+  # Handles seasons and celebrations of the temporale cycle
+  # for a given liturgical year.
   class Temporale
 
+    # How many days in a week
     WEEK = 7
 
-    # year is Integer - the civil year when the liturgical year begins
-    def initialize(year)
+    # Which solemnities can be transferred to Sunday
+    SUNDAY_TRANSFERABLE_SOLEMNITIES =
+      %i(epiphany ascension corpus_christi).freeze
+
+    # @param year [Fixnum]
+    #   the civil year when the liturgical year _begins_
+    # @param extensions [Array<#each_celebration>]
+    #   extensions implementing custom temporale celebrations
+    # @param transfer_to_sunday [Array<Symbol>]
+    #   which solemnities should be transferred to a nearby
+    #   Sunday - see {SUNDAY_TRANSFERABLE_SOLEMNITIES}
+    #   for possible values
+    def initialize(year, extensions: [], transfer_to_sunday: [])
       @year = year
+
+      @extensions = extensions
+      @transfer_to_sunday = transfer_to_sunday.sort
+      validate_sunday_transfer!
+
       prepare_solemnities
     end
 
+    # @return [Fixnum]
     attr_reader :year
 
     class << self
-      # Creates a subclass with specified extension modules included
-      def with_extensions(*extensions)
-        Class.new(self) do
-          extensions.each {|e| include e }
-        end
-      end
-
       # Determines liturgical year for the given date
+      #
+      # @param date [Date]
+      # @return [Fixnum]
       def liturgical_year(date)
         year = date.year
         temporale = Temporale.new year
@@ -32,82 +48,103 @@ module CalendariumRomanum
           return year - 1
         end
 
-        return year
+        year
       end
 
-      # creates a Calendar for the liturgical year including given
+      # Creates an instance for the liturgical year including given
       # date
+      #
+      # @param date [Date]
+      # @return [Temporale]
       def for_day(date)
-        return new(liturgical_year(date))
+        new(liturgical_year(date))
+      end
+
+      # Factory method creating temporale {Celebration}s
+      # with sensible defaults
+      #
+      # See {Celebration#initialize} for argument description.
+      def create_celebration(title, rank, colour, symbol: nil, date: nil)
+        Celebration.new(title, rank, colour, symbol, date, :temporale)
       end
 
       C = Struct.new(:date_method, :celebration)
       private_constant :C
 
-      # implementation detail, not to be touched by client code
+      # @api private
       def celebrations
         @celebrations ||=
           begin
-            [
-              c(:nativity, Ranks::PRIMARY),
-              c(:holy_family, Ranks::FEAST_LORD_GENERAL),
-              c(:mother_of_god, Ranks::SOLEMNITY_GENERAL),
-              c(:epiphany, Ranks::PRIMARY),
-              c(:baptism_of_lord, Ranks::FEAST_LORD_GENERAL),
-              c(:ash_wednesday, Ranks::PRIMARY, Colours::VIOLET),
-              c(:good_friday, Ranks::TRIDUUM, Colours::RED),
-              c(:holy_saturday, Ranks::TRIDUUM, Colours::VIOLET),
-              c(:palm_sunday, Ranks::PRIMARY, Colours::RED),
-              c(:easter_sunday, Ranks::TRIDUUM),
-              c(:ascension, Ranks::PRIMARY),
-              c(:pentecost, Ranks::PRIMARY, Colours::RED),
-              c(:holy_trinity, Ranks::SOLEMNITY_GENERAL),
-              c(:body_blood, Ranks::SOLEMNITY_GENERAL),
-              c(:sacred_heart, Ranks::SOLEMNITY_GENERAL),
-              c(:christ_king, Ranks::SOLEMNITY_GENERAL),
-
-              # Immaculate Heart of Mary is actually (currently the only one)
-              # movable *sanctorale* feast, but as it would make little sense
-              # to add support for movable sanctorale feasts because of
-              # a single one, we cheat a bit and handle it in temporale.
-              c(:immaculate_heart, Ranks::MEMORIAL_GENERAL),
-            ]
+            %i(
+              nativity
+              holy_family
+              mother_of_god
+              epiphany
+              baptism_of_lord
+              ash_wednesday
+              good_friday
+              holy_saturday
+              palm_sunday
+              easter_sunday
+              ascension
+              pentecost
+              holy_trinity
+              corpus_christi
+              mother_of_church
+              sacred_heart
+              christ_king
+              immaculate_heart
+            ).collect do |symbol|
+              date_method = symbol
+              C.new(
+                date_method,
+                CelebrationFactory.public_send(symbol)
+              )
+            end
+            # Immaculate Heart of Mary and Mary, Mother of the Church
+            # are actually movable *sanctorale* feasts,
+            # but as it would make little sense
+            # to add support for movable sanctorale feasts because of
+            # two, we cheat a bit and handle them in temporale.
           end
       end
+    end
 
-      # Hook point for extensions to add new celebrations
-      def add_celebration(date_method, celebration)
-        if self == Temporale
-          raise RuntimeError.new("Don't add celebrations to Temporale itself, subclass it and modify the subclass.")
-        end
-
-        celebrations << C.new(date_method, celebration)
-      end
-
-      private
-
-      def c(date_method, rank, colour=Colours::WHITE)
-        title = proc { I18n.t("temporale.solemnity.#{date_method}") }
-
-        C.new(
-          date_method,
-          Celebration.new(title, rank, colour)
-        )
-      end
+    # Does this instance transfer the specified solemnity to Sunday?
+    #
+    # @param solemnity [Symbol]
+    # @return [Boolean]
+    def transferred_to_sunday?(solemnity)
+      @transfer_to_sunday.include?(solemnity)
     end
 
+    # First day of the liturgical year
+    #
+    # @return [Date]
     def start_date
       first_advent_sunday
     end
 
+    # Last day of the liturgical year
+    #
+    # @return [Date]
     def end_date
-      Dates.first_advent_sunday(year+1) - 1
+      Dates.first_advent_sunday(year + 1) - 1
     end
 
+    # Date range of the liturgical year
+    #
+    # @return [Range<Date>]
     def date_range
       start_date .. end_date
     end
 
+    # Check that the date belongs to the liturgical year.
+    # If it does not, throw exception.
+    #
+    # @param date [Date]
+    # @return [void]
+    # @raise [RangeError]
     def range_check(date)
       # necessary in order to handle Date correctly
       date = date.to_date if date.class != Date
@@ -117,49 +154,84 @@ module CalendariumRomanum
       end
     end
 
-    %i(
-    first_advent_sunday
-    nativity
-    holy_family
-    mother_of_god
-    epiphany
-    baptism_of_lord
-    ash_wednesday
-    palm_sunday
-    good_friday
-    holy_saturday
-    easter_sunday
-    ascension
-    pentecost
-    holy_trinity
-    body_blood
-    sacred_heart
-    immaculate_heart
-    christ_king
-    ).each do |feast|
-      define_method feast do
-        Dates.public_send feast, year
+    # @!method nativity
+    #   @return [Date]
+    # @!method holy_family
+    #   @return [Date]
+    # @!method mother_of_god
+    #   @return [Date]
+    # @!method epiphany
+    #   @return [Date]
+    # @!method baptism_of_lord
+    #   @return [Date]
+    # @!method ash_wednesday
+    #   @return [Date]
+    # @!method good_friday
+    #   @return [Date]
+    # @!method holy_saturday
+    #   @return [Date]
+    # @!method palm_sunday
+    #   @return [Date]
+    # @!method easter_sunday
+    #   @return [Date]
+    # @!method ascension
+    #   @return [Date]
+    # @!method pentecost
+    #   @return [Date]
+    # @!method holy_trinity
+    #   @return [Date]
+    # @!method corpus_christi
+    #   @return [Date]
+    # @!method mother_of_church
+    #   @return [Date]
+    # @!method sacred_heart
+    #   @return [Date]
+    # @!method christ_king
+    #   @return [Date]
+    # @!method immaculate_heart
+    #   @return [Date]
+    # @!method first_advent_sunday
+    #   @return [Date]
+    (celebrations.collect(&:date_method) + [:first_advent_sunday])
+      .each do |feast|
+      if SUNDAY_TRANSFERABLE_SOLEMNITIES.include? feast
+        define_method feast do
+          Dates.public_send feast, year, sunday: transferred_to_sunday?(feast)
+        end
+      elsif feast == :baptism_of_lord
+        define_method feast do
+          Dates.public_send feast, year, epiphany_on_sunday: transferred_to_sunday?(:epiphany)
+        end
+      else
+        define_method feast do
+          Dates.public_send feast, year
+        end
       end
     end
 
-    # which liturgical season is it?
+    # Determine liturgical season for a given date
+    #
+    # @param date [Date]
+    # @return [Season]
+    # @raise [RangeError]
+    #   if the given date doesn't belong to the liturgical year
     def season(date)
       range_check date
 
-      if first_advent_sunday <= date and
-          nativity > date then
+      if (first_advent_sunday <= date) &&
+         nativity > date
         Seasons::ADVENT
 
-      elsif nativity <= date and
-          baptism_of_lord >= date then
+      elsif (nativity <= date) &&
+            (baptism_of_lord >= date)
         Seasons::CHRISTMAS
 
-      elsif ash_wednesday <= date and
-          easter_sunday > date then
+      elsif (ash_wednesday <= date) &&
+            easter_sunday > date
         Seasons::LENT
 
-      elsif easter_sunday <= date and
-          pentecost >= date then
+      elsif (easter_sunday <= date) &&
+            (pentecost >= date)
         Seasons::EASTER
 
       else
@@ -167,6 +239,10 @@ module CalendariumRomanum
       end
     end
 
+    # When the specified liturgical season begins
+    #
+    # @param s [Season]
+    # @return [Date]
     def season_beginning(s)
       case s
       when Seasons::ADVENT
@@ -177,18 +253,24 @@ module CalendariumRomanum
         ash_wednesday
       when Seasons::EASTER
         easter_sunday
-      else # ordinary time
-        Dates.monday_after(baptism_of_lord)
+      when Seasons::ORDINARY # ordinary time
+        baptism_of_lord + 1
+      else
+        raise ArgumentError.new('unsupported season')
       end
     end
 
+    # Determine week of a season for a given date
+    #
+    # @param seasonn [Season]
+    # @param date [Date]
     def season_week(seasonn, date)
       week1_beginning = season_beginning = season_beginning(seasonn)
       unless season_beginning.sunday?
         week1_beginning = Dates.sunday_after(season_beginning)
       end
 
-      week = date_difference(date, week1_beginning) / Temporale::WEEK + 1
+      week = date_difference(date, week1_beginning) / WEEK + 1
 
       if seasonn == Seasons::ORDINARY
         # ordinary time does not begin with Sunday, but the first week
@@ -196,19 +278,32 @@ module CalendariumRomanum
         week += 1
 
         if date > pentecost
-          weeks_after_date = date_difference(Dates.first_advent_sunday(@year + 1), date) / 7
+          weeks_after_date = date_difference(Dates.first_advent_sunday(@year + 1), date) / WEEK
           week = 34 - weeks_after_date
           week += 1 if date.sunday?
         end
       end
 
-      return week
+      week
+    end
+
+    # Retrieve temporale celebration for the given day
+    #
+    # @param date [Date]
+    # @return [Celebration]
+    # @since 0.6.0
+    def [](date)
+      @solemnities[date] || @feasts[date] || sunday(date) || @memorials[date] || ferial(date)
     end
 
-    # returns a Celebration
-    # scheduled for the given day
+    # Retrieve temporale celebration for the given day
     #
-    # expected arguments: Date or two Integers (month, day)
+    # @overload get(date)
+    #   @param date [Date]
+    # @overload get(month, day)
+    #   @param month [Fixnum]
+    #   @param day [Fixnum]
+    # @return (see #[])
     def get(*args)
       if args.size == 1 && args[0].is_a?(Date)
         date = args[0]
@@ -220,9 +315,22 @@ module CalendariumRomanum
         end
       end
 
-      return @solemnities[date] || @feasts[date] || sunday(date) || @memorials[date] || ferial(date)
+      self[date]
     end
 
+    # @return [Boolean]
+    # @since 0.6.0
+    def ==(b)
+      self.class == b.class &&
+        year == b.year &&
+        transfer_to_sunday == b.transfer_to_sunday &&
+        Set.new(extensions) == Set.new(b.extensions)
+    end
+
+    protected
+
+    attr_reader :transfer_to_sunday, :extensions
+
     private
 
     # seasons when Sundays have higher rank
@@ -240,7 +348,7 @@ module CalendariumRomanum
       week = Ordinalizer.ordinal season_week(seas, date)
       title = I18n.t "temporale.#{seas.to_sym}.sunday", week: week
 
-      return Celebration.new title, rank, seas.colour
+      self.class.create_celebration title, rank, seas.colour
     end
 
     def ferial(date)
@@ -252,6 +360,8 @@ module CalendariumRomanum
       when Seasons::ADVENT
         if date >= Date.new(@year, 12, 17)
           rank = Ranks::FERIAL_PRIVILEGED
+          nth = Ordinalizer.ordinal(date.day)
+          title = I18n.t 'temporale.advent.before_christmas', day: nth
         end
       when Seasons::CHRISTMAS
         if date < mother_of_god
@@ -260,32 +370,32 @@ module CalendariumRomanum
           nth = Ordinalizer.ordinal(date.day - nativity.day + 1) # 1-based counting
           title = I18n.t 'temporale.christmas.nativity_octave.ferial', day: nth
         elsif date > epiphany
-          title = I18n.t "temporale.christmas.after_epiphany.ferial", weekday: I18n.t("weekday.#{date.wday}")
+          title = I18n.t 'temporale.christmas.after_epiphany.ferial', weekday: I18n.t("weekday.#{date.wday}")
         end
       when Seasons::LENT
         if week == 0
-          title = I18n.t "temporale.lent.after_ashes.ferial", weekday: I18n.t("weekday.#{date.wday}")
+          title = I18n.t 'temporale.lent.after_ashes.ferial', weekday: I18n.t("weekday.#{date.wday}")
         elsif date > palm_sunday
           rank = Ranks::PRIMARY
-          title = I18n.t "temporale.lent.holy_week.ferial", weekday: I18n.t("weekday.#{date.wday}")
+          title = I18n.t 'temporale.lent.holy_week.ferial', weekday: I18n.t("weekday.#{date.wday}")
         end
         rank = Ranks::FERIAL_PRIVILEGED unless rank > Ranks::FERIAL_PRIVILEGED
       when Seasons::EASTER
         if week == 1
           rank = Ranks::PRIMARY
-          title = I18n.t "temporale.easter.octave.ferial", weekday: I18n.t("weekday.#{date.wday}")
+          title = I18n.t 'temporale.easter.octave.ferial', weekday: I18n.t("weekday.#{date.wday}")
         end
       end
 
       week_ord = Ordinalizer.ordinal week
       title ||= I18n.t "temporale.#{seas.to_sym}.ferial", week: week_ord, weekday: I18n.t("weekday.#{date.wday}")
 
-      return Celebration.new title, rank, seas.colour
+      self.class.create_celebration title, rank, seas.colour
     end
 
     # helper: difference between two Dates in days
     def date_difference(d1, d2)
-      return (d1 - d2).numerator
+      (d1 - d2).numerator
     end
 
     # prepare dates of temporale solemnities
@@ -295,22 +405,44 @@ module CalendariumRomanum
       @memorials = {}
 
       self.class.celebrations.each do |c|
-        if c.date_method.is_a? Proc
-          date = instance_eval &c.date_method
+        prepare_celebration_date c.date_method, c.celebration
+      end
+
+      @extensions.each do |extension|
+        extension.each_celebration do |date_method, celebration|
+          date_proc = date_method
+          if date_method.is_a? Symbol
+            date_proc = extension.method(date_method)
+          end
+
+          prepare_celebration_date date_proc, celebration
+        end
+      end
+    end
+
+    def prepare_celebration_date(date_method, celebration)
+      date =
+        if date_method.respond_to? :call
+          date_method.call(year)
         else
-          date = public_send(c.date_method)
+          public_send(date_method)
         end
-        celebration = c.celebration
-
-        add_to =
-          if celebration.feast?
-            @feasts
-          elsif celebration.memorial?
-            @memorials
-          else
-            @solemnities
-          end
-        add_to[date] = celebration
+
+      add_to =
+        if celebration.feast?
+          @feasts
+        elsif celebration.memorial?
+          @memorials
+        else
+          @solemnities
+        end
+      add_to[date] = celebration
+    end
+
+    def validate_sunday_transfer!
+      unsupported = @transfer_to_sunday - SUNDAY_TRANSFERABLE_SOLEMNITIES
+      unless unsupported.empty?
+        raise RuntimeError.new("Transfer of #{unsupported.inspect} to a Sunday not supported. Only #{SUNDAY_TRANSFERABLE_SOLEMNITIES} are allowed.")
       end
     end
   end