calendarium-romanum 0.2.1 → 0.7.0

data/lib/calendarium-romanum/sanctorale_factory.rb

@@ -1,15 +1,50 @@
 module CalendariumRomanum
-  # conveniently creates sanctorale from several data files
+  # Utility loading {Sanctorale} from several sources
+  # and building a single {Sanctorale} by layering them
+  # over each other.
   class SanctoraleFactory
     class << self
-      # layers several sanctorale instances.
+      # Takes several {Sanctorale} instances, returns a new one,
+      # resulting by merging them all together
+      # (using {Sanctorale#update})
+      #
+      # @return [Sanctorale]
+      #
+      # @example
+      #   include CalendariumRomanum
+      #
+      #   prague_sanctorale = SanctoraleFactory.create_layered(
+      #     Data['czech-cs'].load, # Czech Republic
+      #     Data['czech-cechy-cs'].load, # Province of Bohemia
+      #     Data['czech-praha-cs'].load, # Archdiocese of Prague
+      #   )
       def create_layered(*instances)
         r = Sanctorale.new
         instances.each {|i| r.update i }
+
+        metadata = instances
+                     .collect(&:metadata)
+                     .select {|i| i.is_a? Hash }
+        r.metadata = metadata.inject((metadata.first || {}).dup) {|merged,i| merged.update i }
+        r.metadata.delete 'extends'
+        r.metadata['components'] = instances.collect(&:metadata)
+
         r
       end
 
-      # loads and layers several sanctorale instances.
+      # Takes several filesystem paths, loads a {Sanctorale}
+      # from each of them (using {SanctoraleLoader})
+      # and then merges them (using {.create_layered})
+      #
+      # @return [Sanctorale]
+      #
+      # @example
+      #   include CalendariumRomanum
+      #
+      #   my_sanctorale = SanctoraleFactory.load_layered_from_files(
+      #     'my_data/general_calendar.txt',
+      #     'my_data/particular_calendar.txt'
+      #   )
       def load_layered_from_files(*paths)
         loader = SanctoraleLoader.new
         instances = paths.collect do |p|
@@ -17,6 +52,42 @@ module CalendariumRomanum
         end
         create_layered(*instances)
       end
+
+      # Takes a single filesystem path. If the file's YAML front
+      # matter references any parent data files using the
+      # 'extends' key, it loads all the parents and assembles
+      # the resulting {Sanctorale}.
+      # If the data file doesn't reference any parents,
+      # result is the same as {SanctoraleLoader#load_from_file}.
+      #
+      # @return [Sanctorale]
+      # @since 0.7.0
+      def load_with_parents(path)
+        loader = SanctoraleLoader.new
+
+        hierarchy = load_parent_hierarchy(path, loader)
+        return hierarchy.first if hierarchy.size == 1
+
+        create_layered *hierarchy
+      end
+
+      private
+
+      def load_parent_hierarchy(path, loader)
+        main = loader.load_from_file path
+        return [main] unless main.metadata.has_key? 'extends'
+
+        to_merge = [main]
+        parents = main.metadata['extends']
+        parents = [parents] unless parents.is_a? Array
+        parents.reverse.each do |parent_path|
+          expanded_path = File.expand_path parent_path, File.dirname(path)
+          subtree = load_parent_hierarchy(expanded_path, loader)
+          to_merge = subtree + to_merge
+        end
+
+        to_merge
+      end
     end
   end
 end

data/lib/calendarium-romanum/sanctorale_loader.rb

@@ -0,0 +1,176 @@
+require 'yaml'
+
+module CalendariumRomanum
+
+  # Understands a custom plaintext calendar format
+  # and knows how to transform it to {Celebration}s
+  # and fill them in a {Sanctorale}.
+  #
+  # For specification of the data format see {file:data/README.md},
+  # for a complete example see the file describing General Roman Calendar:
+  # {file:data/universal-en.txt}
+  class SanctoraleLoader
+
+    # @api private
+    RANK_CODES = {
+      nil => Ranks::MEMORIAL_OPTIONAL, # default
+      'm' => Ranks::MEMORIAL_GENERAL,
+      'f' => Ranks::FEAST_GENERAL,
+      's' => Ranks::SOLEMNITY_GENERAL
+    }.freeze
+
+    # @api private
+    COLOUR_CODES = {
+      nil => Colours::WHITE, # default
+      'w' => Colours::WHITE,
+      'v' => Colours::VIOLET,
+      'g' => Colours::GREEN,
+      'r' => Colours::RED
+    }.freeze
+
+    # Load from an object which understands +#each_line+
+    #
+    # @param src [String, File, #each_line]
+    #   source of the loaded data
+    # @param dest [Sanctorale, nil]
+    #   objects to populate. If not provided, a new {Sanctorale}
+    #   instance will be created
+    # @return [Sanctorale]
+    # @raise [InvalidDataError]
+    def load(src, dest = nil)
+      dest ||= Sanctorale.new
+
+      in_front_matter = false
+      front_matter = ''
+      month_section = nil
+      src.each_line.with_index(1) do |l, line_num|
+        # skip YAML front matter
+        if line_num == 1 && l.start_with?('---')
+          in_front_matter = true
+          front_matter += l
+          next
+        elsif in_front_matter
+          if l.start_with?('---')
+            in_front_matter = false
+            dest.metadata = YAML.load(front_matter).freeze
+          end
+
+          front_matter += l
+
+          next
+        end
+
+        # strip whitespace and comments
+        l.sub!(/#.*/, '')
+        l.strip!
+        next if l.empty?
+
+        # month section heading
+        n = l.match(/^=\s*(\d+)\s*$/)
+        unless n.nil?
+          month_section = n[1].to_i
+          unless month_section >= 1 && month_section <= 12
+            raise error("Invalid month #{month_section}", line_num)
+          end
+          next
+        end
+
+        begin
+          celebration = load_line l, month_section
+        rescue RangeError, RuntimeError => err
+          raise error(err.message, line_num)
+        end
+
+        dest.add(
+          celebration.date.month,
+          celebration.date.day,
+          celebration
+        )
+      end
+
+      dest
+    end
+
+    alias load_from_string load
+
+    # Load from a filesystem path
+    #
+    # @param filename [String]
+    # @param dest [Sanctorale, nil]
+    # @param encoding [String]
+    # @return (see #load)
+    # @raise (see #load)
+    def load_from_file(filename, dest = nil, encoding = 'utf-8')
+      load File.open(filename, 'r', encoding: encoding), dest
+    end
+
+    private
+
+    def line_regexp
+      @line_regexp ||=
+        begin
+          rank_letters = RANK_CODES.keys.compact.join('')
+          colour_letters = COLOUR_CODES.keys.compact.join('')
+
+          Regexp.new(
+            '^((?<month>\d+)\/)?(?<day>\d+)' + # date
+            '(\s+(?<rank_char>[' + rank_letters + '])?(?<rank_num>\d\.\d{1,2})?)?' + # rank (optional)
+            '(\s+(?<colour>[' + colour_letters + ']))?' + # colour (optional)
+            '(\s+(?<symbol>[\w]{2,}))?' + # symbol (optional)
+            '\s*:(?<title>.*)$', # title
+            Regexp::IGNORECASE
+          )
+        end
+    end
+
+    # parses a line containing celebration record,
+    # returns a single Celebration
+    def load_line(line, month_section = nil)
+      # celebration record
+      m = line.match(line_regexp)
+      if m.nil?
+        raise RuntimeError.new("Syntax error, line skipped '#{line}'")
+      end
+
+      month = (m[:month] || month_section).to_i
+      day = m[:day].to_i
+      rank_char = m[:rank_char]
+      rank_num = m[:rank_num]
+      colour = m[:colour]
+      symbol_str = m[:symbol]
+      title = m[:title]
+
+      rank = RANK_CODES[rank_char && rank_char.downcase]
+
+      if rank_num
+        rank_num = rank_num.to_f
+        rank_by_num = Ranks[rank_num]
+
+        if rank_by_num.nil?
+          raise RuntimeError.new("Invalid celebration rank code #{rank_num}")
+        elsif rank_char && (rank.priority.to_i != rank_by_num.priority.to_i)
+          raise RuntimeError.new("Invalid combination of rank letter #{rank_char.inspect} and number #{rank_num}.")
+        end
+
+        rank = rank_by_num
+      end
+
+      symbol = nil
+      if symbol_str
+        symbol = symbol_str.to_sym
+      end
+
+      Celebration.new(
+        title.strip,
+        rank,
+        COLOUR_CODES[colour && colour.downcase],
+        symbol,
+        AbstractDate.new(month, day)
+      )
+    end
+
+    def error(message, line_number)
+      InvalidDataError.new("L#{line_number}: #{message}")
+    end
+  end
+end

data/lib/calendarium-romanum/temporale.rb

@@ -2,27 +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
 
-    SEASON_COLOUR = {
-                     Seasons::ADVENT => Colours::VIOLET,
-                     Seasons::CHRISTMAS => Colours::WHITE,
-                     Seasons::ORDINARY => Colours::GREEN,
-                     Seasons::LENT => Colours::VIOLET,
-                     Seasons::EASTER => Colours::WHITE,
-                    }
-
-    # year is Integer - the civil year when the liturgical year begins
-    def initialize(year=nil)
+    # 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
-      prepare_solemnities unless @year.nil?
+
+      @extensions = extensions
+      @transfer_to_sunday = transfer_to_sunday.sort
+      validate_sunday_transfer!
+
+      prepare_solemnities
     end
 
+    # @return [Fixnum]
+    attr_reader :year
+
     class << self
       # Determines liturgical year for the given date
+      #
+      # @param date [Date]
+      # @return [Fixnum]
       def liturgical_year(date)
         year = date.year
         temporale = Temporale.new year
@@ -31,225 +48,190 @@ 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))
-      end
-    end
-
-    def start_date(year=nil)
-      first_advent_sunday(year)
-    end
-
-    def end_date(year=nil)
-      year ||= @year
-      first_advent_sunday(year+1) - 1
-    end
-
-    def date_range(year=nil)
-      start_date(year) .. end_date(year)
-    end
-
-    def range_check(date)
-      # necessary in order to handle Date correctly
-      date = date.to_date if date.class != Date
-
-      unless date_range.include? date
-        raise RangeError.new "Date out of range #{date}"
-      end
-    end
-
-    # converts an AbstractDate to a Date in the given
-    # liturgical year
-    def concretize_abstract_date(abstract_date)
-      d = abstract_date.concretize(@year + 1)
-      if date_range.include? d
-        d
-      else
-        abstract_date.concretize(@year)
+        new(liturgical_year(date))
       end
-    end
 
-    def weekday_before(weekday, date)
-      if date.wday == weekday then
-        return date - WEEK
-      elsif weekday < date.wday
-        return date - (date.wday - weekday)
-      else
-        return date - (date.wday + WEEK - weekday)
+      # 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
-    end
 
-    def weekday_after(weekday, date)
-      if date.wday == weekday then
-        return date + WEEK
-      elsif weekday > date.wday
-        return date + (weekday - date.wday)
-      else
-        return date + (WEEK - date.wday + weekday)
+      C = Struct.new(:date_method, :celebration)
+      private_constant :C
+
+      # @api private
+      def celebrations
+        @celebrations ||=
+          begin
+            %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
 
-    def octave_of(date)
-      date + WEEK
+    # 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
 
-    WEEKDAYS = %w{sunday monday tuesday wednesday thursday friday saturday}
-    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
+    # First day of the liturgical year
+    #
+    # @return [Date]
+    def start_date
+      first_advent_sunday
     end
 
-    # first_advent_sunday -> advent_sunday(1)
-    %w{first second third fourth}.each_with_index do |word,i|
-      define_method "#{word}_advent_sunday" do |year=nil|
-        send("advent_sunday", i + 1, year)
-      end
+    # Last day of the liturgical year
+    #
+    # @return [Date]
+    def end_date
+      Dates.first_advent_sunday(year + 1) - 1
     end
 
-    def advent_sunday(num, year=nil)
-      advent_sundays_total = 4
-      unless (1..advent_sundays_total).include? num
-        raise ArgumentError.new "Invalid Advent Sunday #{num}"
-      end
-
-      year ||= @year
-      return sunday_before(nativity(year)) - ((advent_sundays_total - num) * WEEK)
+    # Date range of the liturgical year
+    #
+    # @return [Range<Date>]
+    def date_range
+      start_date .. end_date
     end
 
-    def nativity(year=nil)
-      year ||= @year
-      return Date.new(year, 12, 25)
-    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
 
-    def holy_family(year=nil)
-      year ||= @year
-      xmas = nativity(year)
-      if xmas.sunday?
-        return Date.new(year, 12, 30)
-      else
-        sunday_after(xmas)
+      unless date_range.include? date
+        raise RangeError.new "Date out of range #{date}"
       end
     end
 
-    def mother_of_god(year=nil)
-      octave_of(nativity(year))
-    end
-
-    def epiphany(year=nil)
-      year ||= @year
-      return Date.new(year+1, 1, 6)
-    end
-
-    def baptism_of_lord(year=nil)
-      year ||= @year
-      return sunday_after epiphany(year)
-    end
-
-    def ash_wednesday(year=nil)
-      year ||= @year
-      return easter_sunday(year) - (6 * WEEK + 4)
-    end
-
-    def easter_sunday(year=nil)
-      year ||= @year
-      year += 1
-
-      # algorithm below taken from the 'easter' gem:
-      # 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 += 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)
-      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
-        # Easter occurs in March.
-        return Date.new(y=year, m=3, d=day_easter + 21)
+    # @!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
-        # Easter occurs in April.
-        return Date.new(y=year, m=4, d=day_easter - 10)
+        define_method feast do
+          Dates.public_send feast, year
+        end
       end
     end
 
-    def palm_sunday(year=nil)
-      return easter_sunday(year) - 7
-    end
-
-    def good_friday(year=nil)
-      return easter_sunday(year) - 2
-    end
-
-    def holy_saturday(year=nil)
-      return easter_sunday(year) - 1
-    end
-
-    def ascension(year=nil)
-      return pentecost(year) - 10
-    end
-
-    def pentecost(year=nil)
-      year ||= @year
-      return easter_sunday(year) + 7 * WEEK
-    end
-
-    def holy_trinity(year=nil)
-      sunday_after(pentecost(year))
-    end
-
-    def body_blood(year=nil)
-      thursday_after(holy_trinity(year))
-    end
-
-    def sacred_heart(year=nil)
-      friday_after(sunday_after(body_blood(year)))
-    end
-
-    def christ_king(year=nil)
-      year ||= @year
-      sunday_before(first_advent_sunday(year + 1))
-    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
@@ -257,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
@@ -267,18 +253,24 @@ module CalendariumRomanum
         ash_wednesday
       when Seasons::EASTER
         easter_sunday
-      else # ordinary time
-        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 = sunday_after(season_beginning)
+        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
@@ -286,19 +278,32 @@ module CalendariumRomanum
         week += 1
 
         if date > pentecost
-          weeks_after_date = date_difference(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]
@@ -310,94 +315,134 @@ module CalendariumRomanum
         end
       end
 
-      return solemnity(date) || sunday(date) || ferial(date)
+      self[date]
     end
 
-    private
+    # @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
 
-    # the celebration determination split in methods:
+    protected
 
-    def solemnity(date)
-      if @solemnities.has_key?(date)
-        return @solemnities[date]
-      end
+    attr_reader :transfer_to_sunday, :extensions
 
-      seas = season(date)
-      case seas
-      when Seasons::EASTER
-        if date <= sunday_after(easter_sunday)
-          return Celebration.new '', Ranks::PRIMARY, SEASON_COLOUR[seas]
-        end
-      end
+    private
 
-      return nil
-    end
+    # seasons when Sundays have higher rank
+    SEASONS_SUNDAY_PRIMARY = [Seasons::ADVENT, Seasons::LENT, Seasons::EASTER].freeze
 
     def sunday(date)
       return nil unless date.sunday?
 
       seas = season date
       rank = Ranks::SUNDAY_UNPRIVILEGED
-      if [Seasons::ADVENT, Seasons::LENT, Seasons::EASTER].include?(seas)
+      if SEASONS_SUNDAY_PRIMARY.include?(seas)
         rank = Ranks::PRIMARY
       end
 
-      return Celebration.new '', rank, SEASON_COLOUR[seas]
+      week = Ordinalizer.ordinal season_week(seas, date)
+      title = I18n.t "temporale.#{seas.to_sym}.sunday", week: week
+
+      self.class.create_celebration title, rank, seas.colour
     end
 
     def ferial(date)
       seas = season date
+      week = season_week(seas, date)
       rank = Ranks::FERIAL
+      title = nil
       case seas
       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
           rank = Ranks::FERIAL_PRIVILEGED
+
+          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}")
         end
       when Seasons::LENT
-        rank = Ranks::FERIAL_PRIVILEGED
+        if week == 0
+          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}")
+        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}")
+        end
       end
 
-      return Celebration.new '', rank, SEASON_COLOUR[seas]
+      week_ord = Ordinalizer.ordinal week
+      title ||= I18n.t "temporale.#{seas.to_sym}.ferial", week: week_ord, weekday: I18n.t("weekday.#{date.wday}")
+
+      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 and their octaves
+    # prepare dates of temporale solemnities
     def prepare_solemnities
       @solemnities = {}
+      @feasts = {}
+      @memorials = {}
+
+      self.class.celebrations.each do |c|
+        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
+          public_send(date_method)
+        end
+
+      add_to =
+        if celebration.feast?
+          @feasts
+        elsif celebration.memorial?
+          @memorials
+        else
+          @solemnities
+        end
+      add_to[date] = celebration
+    end
 
-      {
-        nativity: [Ranks::PRIMARY, nil],
-        holy_family: [Ranks::FEAST_LORD_GENERAL, nil],
-        mother_of_god: [Ranks::SOLEMNITY_GENERAL],
-        epiphany: [Ranks::PRIMARY, nil],
-        baptism_of_lord: [Ranks::FEAST_LORD_GENERAL, nil],
-        ash_wednesday: [Ranks::PRIMARY, nil],
-        good_friday: [Ranks::TRIDUUM, Colours::RED],
-        holy_saturday: [Ranks::TRIDUUM, nil],
-        palm_sunday: [Ranks::PRIMARY, Colours::RED],
-        easter_sunday: [Ranks::TRIDUUM, nil],
-        ascension: [Ranks::PRIMARY, Colours::WHITE],
-        pentecost: [Ranks::PRIMARY, Colours::RED],
-        holy_trinity: [Ranks::SOLEMNITY_GENERAL, Colours::WHITE],
-        body_blood: [Ranks::SOLEMNITY_GENERAL, Colours::WHITE],
-        sacred_heart: [Ranks::SOLEMNITY_GENERAL, Colours::WHITE],
-        christ_king: [Ranks::SOLEMNITY_GENERAL, Colours::WHITE],
-      }.each_pair do |method_name, data|
-        date = send(method_name)
-        rank, colour = data
-        @solemnities[date] = Celebration.new(
-                                             proc { I18n.t("temporale.solemnity.#{method_name}") },
-                                             rank,
-                                             colour || SEASON_COLOUR[season(date)]
-                                            )
+    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