calendarium-romanum 0.4.0 → 0.8.0

data/lib/calendarium-romanum/sanctorale_writer.rb

@@ -0,0 +1,119 @@
+require 'yaml'
+
+module CalendariumRomanum
+
+  # Understands a custom plaintext calendar format
+  # and knows how to transform the {Celebration}s in a
+  # {Sanctorale} to this format.
+  #
+  # For specification of the data format see {file:data/README.md}
+  # of the data directory, For a complete example see e.g.
+  # {file:universal-en.txt the file describing General Roman Calendar}.
+  #
+  # @since 0.8.0
+  class SanctoraleWriter
+
+    # @api private
+    RANK_CODES = {
+      Ranks::TRIDUUM => 's1.1',
+      Ranks::PRIMARY => 's1.2',
+      Ranks::SOLEMNITY_GENERAL => 's',
+      Ranks::SOLEMNITY_PROPER => 's1.4',
+
+      Ranks::FEAST_LORD_GENERAL => 'f2.5',
+      Ranks::SUNDAY_UNPRIVILEGED => 'f2.6',
+      Ranks::FEAST_GENERAL => 'f',
+      Ranks::FEAST_PROPER => 'f2.8',
+      Ranks::FERIAL_PRIVILEGED => 'f2.9',
+
+      Ranks::MEMORIAL_GENERAL => 'm',
+      Ranks::MEMORIAL_PROPER => 'm3.11',
+      Ranks::MEMORIAL_OPTIONAL => 'm3.12',
+      Ranks::FERIAL => 'm3.13',
+
+      Ranks::COMMEMORATION => '4.0'
+    }.freeze
+
+    # @api private
+    COLOUR_CODES = {
+      Colours::WHITE => 'W',
+      Colours::VIOLET => 'V',
+      Colours::GREEN => 'G',
+      Colours::RED => 'R'
+    }.freeze
+
+    # Write to an object which understands +#<<+
+    #
+    # @param src [Sanctorale]
+    #   source of the loaded data
+    # @param dest [String, File, #<<]
+    #   object to populate. If not provided, a new {String}
+    #   instance will be created and returned
+    # @return [String]
+    def write(src, dest = nil)
+      dest ||= String.new
+
+      # Write metadata to YAML if present
+      unless src.metadata.nil? || src.metadata.empty?
+        dest << src.metadata.to_yaml
+        dest << "---\n"
+      end
+
+      # Write each celebration, grouped by month with headings
+      current_month = 0
+      src.each_day.sort_by{ |date, _| date }.each do |date, celebrations|
+        if date.month > current_month
+          current_month = date.month
+          dest << "\n= #{current_month}\n"
+        end
+
+        celebrations.each do |c|
+          dest << celebration_line(date, c)
+          dest << "\n"
+        end
+      end
+
+      dest
+    end
+
+    alias write_to_string write
+
+    # Write to a filesystem path
+    #
+    # @param sanctorale [Sanctorale]
+    # @param filename [String]
+    # @param encoding [String]
+    # @return [void]
+    def write_to_file(sanctorale, filename, encoding = 'utf-8')
+      File.open(filename, 'w', encoding: encoding) do |f|
+        write(sanctorale, f)
+      end
+    end
+
+    private
+
+    # Convert a {Celebration} to a {String} for writing
+    def celebration_line(date, celebration)
+      line = "#{date.day} "
+
+      unless celebration.rank == Ranks::MEMORIAL_OPTIONAL
+        code = RANK_CODES[celebration.rank]
+        line << "#{code} "
+      end
+
+      unless celebration.colour == Colours::WHITE
+        code = COLOUR_CODES[celebration.colour]
+        line << "#{code} "
+      end
+
+      unless celebration.symbol.nil?
+        line << "#{celebration.symbol} "
+      end
+
+      line << ': '
+      line << celebration.title
+
+      line
+    end
+  end
+end

data/lib/calendarium-romanum/temporale.rb

@@ -2,29 +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
 
+    # Which solemnities can be transferred to Sunday
     SUNDAY_TRANSFERABLE_SOLEMNITIES =
       %i(epiphany ascension corpus_christi).freeze
 
-    # year is Integer - the civil year when the liturgical year begins
+    # @param year [Integer]
+    #   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
+      @transfer_to_sunday = transfer_to_sunday.sort
       validate_sunday_transfer!
 
       prepare_solemnities
     end
 
+    # @return [Integer]
     attr_reader :year
 
     class << self
       # Determines liturgical year for the given date
+      #
+      # @param date [Date]
+      # @return [Integer]
       def liturgical_year(date)
         year = date.year
         temporale = Temporale.new year
@@ -33,77 +48,111 @@ 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, sunday: nil)
+        Celebration.new(
+          title: title,
+          rank: rank,
+          colour: colour,
+          symbol: symbol,
+          date: date,
+          cycle: :temporale,
+          sunday: sunday
+        )
       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(:corpus_christi, 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
-
-      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
     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
@@ -113,26 +162,46 @@ 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
-    corpus_christi
-    sacred_heart
-    immaculate_heart
-    christ_king
-    ).each do |feast|
+    # @!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)
@@ -148,24 +217,33 @@ module CalendariumRomanum
       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 &&
+            good_friday > date
         Seasons::LENT
 
-      elsif easter_sunday <= date and
-          pentecost >= date then
+      elsif good_friday <= date &&
+            easter_sunday >= date
+        Seasons::TRIDUUM
+
+      elsif easter_sunday < date &&
+            pentecost >= date
         Seasons::EASTER
 
       else
@@ -173,6 +251,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
@@ -181,13 +263,21 @@ module CalendariumRomanum
         nativity
       when Seasons::LENT
         ash_wednesday
+      when Seasons::TRIDUUM
+        good_friday
       when Seasons::EASTER
-        easter_sunday
-      else # ordinary time
-        Dates.monday_after(baptism_of_lord)
+        easter_sunday + 1
+      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?
@@ -196,25 +286,40 @@ module CalendariumRomanum
 
       week = date_difference(date, week1_beginning) / WEEK + 1
 
-      if seasonn == Seasons::ORDINARY
+      if seasonn == Seasons::ORDINARY || seasonn == Seasons::EASTER
         # ordinary time does not begin with Sunday, but the first week
         # is week 1, not 0
         week += 1
+      end
 
+      if seasonn == Seasons::ORDINARY
         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
 
-    # returns a Celebration
-    # scheduled for the given day
+    # Retrieve temporale celebration for the given day
     #
-    # expected arguments: Date or two Integers (month, day)
+    # @param date [Date]
+    # @return [Celebration]
+    # @since 0.6.0
+    def [](date)
+      @solemnities[date] || @feasts[date] || sunday(date) || @memorials[date] || ferial(date)
+    end
+
+    # Retrieve temporale celebration for the given day
+    #
+    # @overload get(date)
+    #   @param date [Date]
+    # @overload get(month, day)
+    #   @param month [Integer]
+    #   @param day [Integer]
+    # @return (see #[])
     def get(*args)
       if args.size == 1 && args[0].is_a?(Date)
         date = args[0]
@@ -226,9 +331,33 @@ module CalendariumRomanum
         end
       end
 
-      return @solemnities[date] || @feasts[date] || sunday(date) || @memorials[date] || ferial(date)
+      self[date]
+    end
+
+    # Enumerates dates and celebrations
+    #
+    # @yield [Date, Celebration]
+    # @return [void, Enumerator] if called without a block, returns +Enumerator+
+    # @since 0.8.0
+    def each_day
+      return to_enum(__method__) unless block_given?
+
+      date_range.each {|date| yield 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
@@ -246,7 +375,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, sunday: true
     end
 
     def ferial(date)
@@ -258,6 +387,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
@@ -266,32 +397,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
@@ -317,11 +448,12 @@ module CalendariumRomanum
     end
 
     def prepare_celebration_date(date_method, celebration)
-      if date_method.respond_to? :call
-        date = date_method.call(year)
-      else
-        date = public_send(date_method)
-      end
+      date =
+        if date_method.respond_to? :call
+          date_method.call(year)
+        else
+          public_send(date_method)
+        end
 
       add_to =
         if celebration.feast?