calendarium-romanum 0.5.0 → 0.9.0

data/lib/calendarium-romanum/sanctorale_writer.rb

@@ -0,0 +1,124 @@
+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
+
+    # @param front_matter [Boolean] Should YAML front matter be written?
+    def initialize(front_matter: true)
+      @write_front_matter = front_matter
+    end
+
+    # 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 (!@write_front_matter) || 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

@@ -1,51 +1,82 @@
-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
 
-        if date < temporale.first_advent_sunday
+        if date < Dates.first_advent_sunday(year)
           return year - 1
         end
 
         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)
         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
@@ -64,6 +95,7 @@ module CalendariumRomanum
               pentecost
               holy_trinity
               corpus_christi
+              mother_of_church
               sacred_heart
               christ_king
               immaculate_heart
@@ -74,30 +106,50 @@ module CalendariumRomanum
                 CelebrationFactory.public_send(symbol)
               )
             end
-            # Immaculate Heart of Mary is actually (currently the only one)
-            # movable *sanctorale* feast, but as it would make little sense
+            # 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
-            # a single one, we cheat a bit and handle it in temporale.
+            # two, we cheat a bit and handle them in temporale.
           end
       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
     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
@@ -107,6 +159,44 @@ module CalendariumRomanum
       end
     end
 
+    # @!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
@@ -124,24 +214,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) &&
+      if first_advent_sunday <= date &&
          nativity > date
         Seasons::ADVENT
 
-      elsif (nativity <= date) &&
-            (baptism_of_lord >= date)
+      elsif nativity <= date &&
+            baptism_of_lord >= date
         Seasons::CHRISTMAS
 
-      elsif (ash_wednesday <= date) &&
-            easter_sunday > date
+      elsif ash_wednesday <= date &&
+            good_friday > date
         Seasons::LENT
 
-      elsif (easter_sunday <= date) &&
-            (pentecost >= date)
+      elsif good_friday <= date &&
+            easter_sunday >= date
+        Seasons::TRIDUUM
+
+      elsif easter_sunday < date &&
+            pentecost >= date
         Seasons::EASTER
 
       else
@@ -149,6 +248,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
@@ -157,15 +260,21 @@ module CalendariumRomanum
         nativity
       when Seasons::LENT
         ash_wednesday
+      when Seasons::TRIDUUM
+        good_friday
       when Seasons::EASTER
-        easter_sunday
-      when Seasons::ORDINARY # ordinary time
+        easter_sunday + 1
+      when Seasons::ORDINARY
         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?
@@ -174,11 +283,13 @@ 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) / WEEK
           week = 34 - weeks_after_date
@@ -189,10 +300,25 @@ module CalendariumRomanum
       week
     end
 
-    # returns a Celebration
-    # scheduled for the given day
+    # Retrieve temporale celebration for the given day
+    #
+    # @param date [Date]
+    # @return [Celebration]
+    # @since 0.6.0
+    def [](date)
+      sw = season_and_week(date)
+
+      @solemnities[date] || @feasts[date] || sunday(date, sw) || @memorials[date] || ferial(date, sw)
+    end
+
+    # 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 [Integer]
+    #   @param day [Integer]
+    # @return (see #[])
     def get(*args)
       if args.size == 1 && args[0].is_a?(Date)
         date = args[0]
@@ -204,35 +330,80 @@ module CalendariumRomanum
         end
       end
 
-      @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
+
+    # Does this instance provide celebration identified by symbol +symbol+?
+    #
+    # @param symbol [Symbol]
+    # @return [Boolean]
+    # @since 0.9.0
+    def provides_celebration?(symbol)
+      @all_celebration_symbols.include? symbol
     end
 
+    protected
+
+    attr_reader :transfer_to_sunday, :extensions
+
     private
 
+    SeasonWeek = Struct.new(:season, :week)
+    private_constant :SeasonWeek
+
+    def season_and_week(date)
+      s = season(date)
+      w = season_week(s, date)
+
+      SeasonWeek.new(s, w)
+    end
+
     # seasons when Sundays have higher rank
     SEASONS_SUNDAY_PRIMARY = [Seasons::ADVENT, Seasons::LENT, Seasons::EASTER].freeze
 
-    def sunday(date)
+    def sunday(date, season_week)
       return nil unless date.sunday?
 
-      seas = season date
       rank = Ranks::SUNDAY_UNPRIVILEGED
-      if SEASONS_SUNDAY_PRIMARY.include?(seas)
+      if SEASONS_SUNDAY_PRIMARY.include?(season_week.season)
         rank = Ranks::PRIMARY
       end
 
-      week = Ordinalizer.ordinal season_week(seas, date)
-      title = I18n.t "temporale.#{seas.to_sym}.sunday", week: week
+      week = Ordinalizer.ordinal season_week.week
+      title = I18n.t "temporale.#{season_week.season.to_sym}.sunday", week: week
 
-      Celebration.new title, rank, seas.colour
+      self.class.create_celebration title, rank, season_week.season.colour, sunday: true
     end
 
-    def ferial(date)
-      seas = season date
-      week = season_week(seas, date)
+    def ferial(date, season_week = nil)
+      # Normally +season_week+ is provided, but the method is once called also from Calendar
+      # and we definitely don't want Calendar to care that much about Temporale internals
+      # So as to know how to retrieve the value, so in that case we provide it ourselves.
+      season_week ||= season_and_week(date)
+
       rank = Ranks::FERIAL
       title = nil
-      case seas
+      case season_week.season
       when Seasons::ADVENT
         if date >= Date.new(@year, 12, 17)
           rank = Ranks::FERIAL_PRIVILEGED
@@ -249,7 +420,7 @@ module CalendariumRomanum
           title = I18n.t 'temporale.christmas.after_epiphany.ferial', weekday: I18n.t("weekday.#{date.wday}")
         end
       when Seasons::LENT
-        if week == 0
+        if season_week.week == 0
           title = I18n.t 'temporale.lent.after_ashes.ferial', weekday: I18n.t("weekday.#{date.wday}")
         elsif date > palm_sunday
           rank = Ranks::PRIMARY
@@ -257,16 +428,16 @@ module CalendariumRomanum
         end
         rank = Ranks::FERIAL_PRIVILEGED unless rank > Ranks::FERIAL_PRIVILEGED
       when Seasons::EASTER
-        if week == 1
+        if season_week.week == 1
           rank = Ranks::PRIMARY
           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}")
+      week_ord = Ordinalizer.ordinal season_week.week
+      title ||= I18n.t "temporale.#{season_week.season.to_sym}.ferial", week: week_ord, weekday: I18n.t("weekday.#{date.wday}")
 
-      Celebration.new title, rank, seas.colour
+      self.class.create_celebration title, rank, season_week.season.colour
     end
 
     # helper: difference between two Dates in days
@@ -294,6 +465,15 @@ module CalendariumRomanum
           prepare_celebration_date date_proc, celebration
         end
       end
+
+      @all_celebration_symbols = Set.new(
+        @solemnities
+          .merge(@feasts)
+          .merge(@memorials)
+          .each_value
+          .collect(&:symbol)
+          .compact # all should have a symbol, but we really want to prevent nil here
+      )
     end
 
     def prepare_celebration_date(date_method, celebration)