calendarium-romanum 0.8.0 → 0.9.0

data/lib/calendarium-romanum/data.rb

@@ -40,6 +40,7 @@ module CalendariumRomanum
     GENERAL_ROMAN_ENGLISH = SanctoraleFile.new('universal-en.txt')
     GENERAL_ROMAN_FRENCH = SanctoraleFile.new('universal-fr.txt')
     GENERAL_ROMAN_ITALIAN = SanctoraleFile.new('universal-it.txt')
+    GENERAL_ROMAN_PORTUGUESE = SanctoraleFile.new('universal-pt.txt')
     GENERAL_ROMAN_SPANISH = SanctoraleFile.new('universal-es.txt')
     CZECH = SanctoraleFile.new('czech-cs.txt')
 
@@ -51,6 +52,7 @@ module CalendariumRomanum
         GENERAL_ROMAN_ENGLISH,
         GENERAL_ROMAN_FRENCH,
         GENERAL_ROMAN_ITALIAN,
+        GENERAL_ROMAN_PORTUGUESE,
         GENERAL_ROMAN_SPANISH,
         CZECH,
       ] \

data/lib/calendarium-romanum/enum.rb

@@ -14,16 +14,14 @@ module CalendariumRomanum
     def values(index_by: nil)
       defined?(@indexed) && raise(RuntimeError.new('initialized repeatedly'))
 
-      @indexed = {}
       @all = yield.freeze
+      @all.each &:freeze
 
+      @indexed = {}
       @all.each_with_index do |val, i|
-        val.freeze
-
         key = index_by ? val.public_send(index_by) : i
         @indexed[key] = val
       end
-
       @indexed.freeze
     end
 

data/lib/calendarium-romanum/enums.rb

@@ -154,9 +154,13 @@ module CalendariumRomanum
   # Convenience module containing all the colour, season and rank constants
   # for easy including
   #
+  # Caveat: there is both a {Season} and a {Rank} with the identifier +TRIDUUM+.
+  # Due to this name clash, only the {Rank} is easily accessible
+  # using the {Constants} module.
+  #
   # @example
   #   include CalendariumRomanum::Constants
-  #   RED # now all the constants are available in current module
+  #   RED # now all the constants are available in the current module
   #
   # @since 0.8.0
   module Constants

data/lib/calendarium-romanum/sanctorale.rb

@@ -22,6 +22,20 @@ module CalendariumRomanum
       @metadata = nil
     end
 
+    # @!method dup
+    #   Returns a copy of the receiver with properly copied internal
+    #   data structures, i.e. a copy which can be safely modified without
+    #   danger of unintentionally modifying the original instance.
+    #   @return [Sanctorale]
+
+    # @api private
+    def initialize_dup(other)
+      @days = other.days.dup
+      @solemnities = other.solemnities.dup
+      @symbols = other.symbols.dup
+      @metadata = Marshal.load Marshal.dump other.metadata # deep copy
+    end
+
     # Content subset - only {Celebration}s in the rank(s) of solemnity.
     #
     # @return [Hash<AbstractDate=>Celebration>]
@@ -135,6 +149,15 @@ module CalendariumRomanum
       rebuild_symbols
     end
 
+    # Returns a new copy containing {Celebration}s from both self and +other+.
+    #
+    # @param other [Sanctorale]
+    # @return [Sanctorale]
+    # @since 0.9.0
+    def merge(other)
+      dup.tap {|dupped| dupped.update other }
+    end
+
     # Retrieves {Celebration}s for the given date
     #
     # @param date [AbstractDate, Date]
@@ -206,9 +229,36 @@ module CalendariumRomanum
         days == b.days
     end
 
+    # Does this instance provide celebration identified by symbol +symbol+?
+    #
+    # @param symbol [Symbol]
+    # @return [Boolean]
+    # @since 0.9.0
+    def provides_celebration?(symbol)
+      @symbols.include? symbol
+    end
+
+    # If the instance contains a {Celebration} identified by the specified symbol,
+    # returns it's date and the {Celebration} itself, nil otherwise.
+    #
+    # @param symbol [Symbol]
+    # @return [Array<AbstractDate, Celebration>, nil]
+    # @since 0.9.0
+    def by_symbol(symbol)
+      return nil unless provides_celebration? symbol
+
+      @days.each_pair do |date, celebrations|
+        found = celebrations.find {|c| c.symbol == symbol }
+        return [date, found] if found
+      end
+
+      # reaching this point would mean that contents of @symbols and @days are not consistent
+      raise 'this point should never be reached'
+    end
+
     protected
 
-    attr_reader :days
+    attr_reader :days, :symbols
 
     # Builds the registry of celebration symbols anew,
     # raises error if any duplicates are found.

data/lib/calendarium-romanum/sanctorale_factory.rb

@@ -42,8 +42,8 @@ module CalendariumRomanum
       #   include CalendariumRomanum
       #
       #   my_sanctorale = SanctoraleFactory.load_layered_from_files(
-      #     'my_data/general_calendar.txt',
-      #     'my_data/particular_calendar.txt'
+      #     'data/czech-cs.txt',
+      #     'data/czech-cechy-cs.txt'
       #   )
       def load_layered_from_files(*paths)
         loader = SanctoraleLoader.new

data/lib/calendarium-romanum/sanctorale_writer.rb

@@ -42,6 +42,11 @@ module CalendariumRomanum
       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]
@@ -54,7 +59,7 @@ module CalendariumRomanum
       dest ||= String.new
 
       # Write metadata to YAML if present
-      unless src.metadata.nil? || src.metadata.empty?
+      unless (!@write_front_matter) || src.metadata.nil? || src.metadata.empty?
         dest << src.metadata.to_yaml
         dest << "---\n"
       end

data/lib/calendarium-romanum/temporale.rb

@@ -1,5 +1,3 @@
-require 'date'
-
 module CalendariumRomanum
 
   # One of the two main {Calendar} components.
@@ -42,9 +40,8 @@ module CalendariumRomanum
       # @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
 
@@ -267,7 +264,7 @@ module CalendariumRomanum
         good_friday
       when Seasons::EASTER
         easter_sunday + 1
-      when Seasons::ORDINARY # ordinary time
+      when Seasons::ORDINARY
         baptism_of_lord + 1
       else
         raise ArgumentError.new('unsupported season')
@@ -309,7 +306,9 @@ module CalendariumRomanum
     # @return [Celebration]
     # @since 0.6.0
     def [](date)
-      @solemnities[date] || @feasts[date] || sunday(date) || @memorials[date] || ferial(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
@@ -354,36 +353,57 @@ module CalendariumRomanum
         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
 
-      self.class.create_celebration title, rank, seas.colour, sunday: true
+      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
@@ -400,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
@@ -408,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}")
 
-      self.class.create_celebration title, rank, seas.colour
+      self.class.create_celebration title, rank, season_week.season.colour
     end
 
     # helper: difference between two Dates in days
@@ -445,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)

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

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