calendarium-romanum 0.7.1 → 0.8.0

data/lib/calendarium-romanum/enums.rb

@@ -33,7 +33,9 @@ module CalendariumRomanum
   end
 
   # Standard set of liturgical colours
-  class Colours < Enum
+  module Colours
+    extend Enum
+
     GREEN = Colour.new(:green)
     VIOLET = Colour.new(:violet)
     WHITE = Colour.new(:white)
@@ -67,15 +69,20 @@ module CalendariumRomanum
 
     # Liturgical colour of the season's Sundays and ferials
     #
-    # @return [Colour]
+    # May be +nil+ if there is no single colour.
+    #
+    # @return [Colour, nil]
     attr_reader :colour
   end
 
   # Standard set of liturgical seasons
-  class Seasons < Enum
+  module Seasons
+    extend Enum
+
     ADVENT = Season.new(:advent, Colours::VIOLET)
     CHRISTMAS = Season.new(:christmas, Colours::WHITE)
     LENT = Season.new(:lent, Colours::VIOLET)
+    TRIDUUM = Season.new(:triduum, nil)
     EASTER = Season.new(:easter, Colours::WHITE)
     ORDINARY = Season.new(:ordinary, Colours::GREEN)
 
@@ -84,6 +91,7 @@ module CalendariumRomanum
         ADVENT,
         CHRISTMAS,
         LENT,
+        TRIDUUM,
         EASTER,
         ORDINARY,
       ]
@@ -95,7 +103,9 @@ module CalendariumRomanum
   LECTIONARY_CYCLES = [:A, :B, :C].freeze
 
   # Celebration ranks as specified in the Table of Liturgical Days
-  class Ranks < Enum
+  module Ranks
+    extend Enum
+
     TRIDUUM           = Rank.new(1.1, 'rank.1_1')
     PRIMARY           = Rank.new(1.2, 'rank.1_2') # description may not be exact
     SOLEMNITY_GENERAL = Rank.new(1.3, 'rank.1_3', 'rank.short.solemnity') # description may not be exact
@@ -140,4 +150,18 @@ module CalendariumRomanum
       ]
     end
   end
+
+  # Convenience module containing all the colour, season and rank constants
+  # for easy including
+  #
+  # @example
+  #   include CalendariumRomanum::Constants
+  #   RED # now all the constants are available in current module
+  #
+  # @since 0.8.0
+  module Constants
+    include Colours
+    include Seasons
+    include Ranks
+  end
 end

data/lib/calendarium-romanum/ordinalizer.rb

@@ -6,11 +6,11 @@ module CalendariumRomanum
   # Used by {Temporale} for building names of Sundays and ferials.
   class Ordinalizer
     class << self
-      # @param number [Fixnum] number to build ordinal for
+      # @param number [Integer] number to build ordinal for
       # @param locale [Symbol,nil]
       #   locale; +I18n.locale+ (i.e. the `i18n` gem's current locale)
       #   is used if not provided
-      # @return [String, Fixnum]
+      # @return [String, Integer]
       #   ordinal, or unchanged +number+ if +Ordinalizer+ cannot
       #   build ordinals for the given locale
       def ordinal(number, locale: nil)

data/lib/calendarium-romanum/perpetual_calendar.rb

@@ -18,6 +18,8 @@ module CalendariumRomanum
     #   +Hash+ of arguments for {Temporale#initialize}.
     #   +temporale_factory+ and +temporale_options+ are mutually
     #   exclusive - pass either (or none) of them, never both.
+    # @param vespers [Boolean]
+    #   See argument of the same name to {Calendar#initialize}
     # @param cache [Hash]
     #   object to be used as internal cache of {Calendar} instances -
     #   anything exposing +#[]=+ and +#[]+ and "behaving mostly like
@@ -29,13 +31,14 @@ module CalendariumRomanum
     #   by huge amount of cached {Calendar} instances.
     #   (By default, once a {Calendar} for a certain year is built,
     #   it is cached for the +PerpetualCalendar+ instances' lifetime.)
-    def initialize(sanctorale: nil, temporale_factory: nil, temporale_options: nil, cache: {})
+    def initialize(sanctorale: nil, temporale_factory: nil, temporale_options: nil, vespers: false, cache: {})
       if temporale_factory && temporale_options
         raise ArgumentError.new('Specify either temporale_factory or temporale_options, not both')
       end
 
       @sanctorale = sanctorale
       @temporale_factory = temporale_factory || build_temporale_factory(temporale_options)
+      @vespers = vespers
 
       @cache = cache
     end
@@ -73,7 +76,7 @@ module CalendariumRomanum
 
     # Returns a Calendar instance for the specified liturgical year
     #
-    # @param year [Fixnum]
+    # @param year [Integer]
     # @return [Calendar]
     def calendar_for_year(year)
       calendar_instance year
@@ -90,7 +93,7 @@ module CalendariumRomanum
       if @cache.has_key? year
         @cache[year]
       else
-        @cache[year] = Calendar.new(year, @sanctorale, @temporale_factory.call(year))
+        @cache[year] = Calendar.new(year, @sanctorale, @temporale_factory.call(year), vespers: @vespers)
       end
     end
   end

data/lib/calendarium-romanum/rank.rb

@@ -1,6 +1,7 @@
 module CalendariumRomanum
   # Celebration rank
   class Rank
+    include RankPredicates
     include Comparable
 
     # @param priority [Float, nil] number in the Table of Liturgical Days
@@ -46,32 +47,25 @@ module CalendariumRomanum
       other.priority <=> priority
     end
 
-    # @return [Boolean]
-    def solemnity?
-      priority.to_i == 1
-    end
-
-    # @return [Boolean]
-    # @since 0.6.0
-    def sunday?
-      self == Ranks::SUNDAY_UNPRIVILEGED
-    end
+    # Returns the next higher rank.
+    #
+    # Allows constructing ranges of ranks.
+    #
+    # @return [Rank]
+    # @since 0.8.0
+    def succ
+      all = CR::Ranks.all
+      index = all.index(self)
+      raise StopIteration.new if index == 0
 
-    # @return [Boolean]
-    def feast?
-      priority.to_i == 2
+      all[index - 1]
     end
 
-    # @return [Boolean]
-    def memorial?
-      priority.to_i == 3 && priority <= 3.12
-    end
+    private
 
-    # @return [Boolean]
-    # @since 0.6.0
-    def ferial?
-      self == Ranks::FERIAL ||
-        self == Ranks::FERIAL_PRIVILEGED
+    # Required by the {RankPredicates} mixin
+    def rank
+      self
     end
   end
 end

data/lib/calendarium-romanum/rank_predicates.rb

@@ -0,0 +1,43 @@
+module CalendariumRomanum
+  # Mixin providing rank-describing predicates.
+  # Expects the including class to have instance method +#rank+ returning a {Rank}.
+  module RankPredicates
+    # @return [Boolean]
+    def solemnity?
+      rank.priority.to_i == 1
+    end
+
+    # @return [Boolean]
+    # @since 0.6.0
+    def sunday?
+      rank == Ranks::SUNDAY_UNPRIVILEGED
+    end
+
+    # @return [Boolean]
+    def feast?
+      rank.priority.to_i == 2
+    end
+
+    # @return [Boolean]
+    def memorial?
+      rank.priority.to_i == 3 && rank.priority <= 3.12
+    end
+
+    # @return [Boolean]
+    def optional_memorial?
+      rank == Ranks::MEMORIAL_OPTIONAL
+    end
+
+    # @return [Boolean]
+    def obligatory_memorial?
+      memorial? && !optional_memorial?
+    end
+
+    # @return [Boolean]
+    # @since 0.6.0
+    def ferial?
+      rank == Ranks::FERIAL ||
+        rank == Ranks::FERIAL_PRIVILEGED
+    end
+  end
+end

data/lib/calendarium-romanum/sanctorale.rb

@@ -45,8 +45,8 @@ module CalendariumRomanum
 
     # Adds a new {Celebration}
     #
-    # @param month [Fixnum]
-    # @param day [Fixnum]
+    # @param month [Integer]
+    # @param day [Integer]
     # @param celebration [Celebration]
     # @return [void]
     # @raise [ArgumentError]
@@ -84,8 +84,8 @@ module CalendariumRomanum
 
     # Replaces content of the given day by given {Celebration}s
     #
-    # @param month [Fixnum]
-    # @param day [Fixnum]
+    # @param month [Integer]
+    # @param day [Integer]
     # @param celebrations [Array<Celebration>]
     # @param symbol_uniqueness [true|false]
     #   allows disabling symbol uniqueness check.
@@ -150,8 +150,8 @@ module CalendariumRomanum
     # @overload get(date)
     #   @param date[AbstractDate, Date]
     # @overload get(month, day)
-    #   @param month [Fixnum]
-    #   @param day [Fixnum]
+    #   @param month [Integer]
+    #   @param day [Integer]
     # @return (see #[])
     def get(*args)
       if args.size == 1 && args[0].is_a?(Date)
@@ -179,7 +179,7 @@ module CalendariumRomanum
 
     # Returns count of _days_ with {Celebration}s filled
     #
-    # @return [Fixnum]
+    # @return [Integer]
     def size
       @days.size
     end
@@ -219,7 +219,8 @@ module CalendariumRomanum
       @days.each_pair do |date,celebrations|
         celebrations.each do |celebration|
           if @symbols.include?(celebration.symbol) &&
-             !duplicates.include?(celebration.symbol)
+             !duplicates.include?(celebration.symbol) &&
+             !celebration.symbol.nil?
             duplicates << celebration.symbol
           end
 

data/lib/calendarium-romanum/sanctorale_loader.rb

@@ -15,8 +15,12 @@ module CalendariumRomanum
     RANK_CODES = {
       nil => Ranks::MEMORIAL_OPTIONAL, # default
       'm' => Ranks::MEMORIAL_GENERAL,
+      'mp' => Ranks::MEMORIAL_PROPER,
       'f' => Ranks::FEAST_GENERAL,
-      's' => Ranks::SOLEMNITY_GENERAL
+      'fl' => Ranks::FEAST_LORD_GENERAL,
+      'fp' => Ranks::FEAST_PROPER,
+      's' => Ranks::SOLEMNITY_GENERAL,
+      'sp' => Ranks::SOLEMNITY_PROPER,
     }.freeze
 
     # @api private
@@ -109,12 +113,12 @@ module CalendariumRomanum
     def line_regexp
       @line_regexp ||=
         begin
-          rank_letters = RANK_CODES.keys.compact.join('')
+          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+(?<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

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

@@ -14,7 +14,7 @@ module CalendariumRomanum
     SUNDAY_TRANSFERABLE_SOLEMNITIES =
       %i(epiphany ascension corpus_christi).freeze
 
-    # @param year [Fixnum]
+    # @param year [Integer]
     #   the civil year when the liturgical year _begins_
     # @param extensions [Array<#each_celebration>]
     #   extensions implementing custom temporale celebrations
@@ -32,14 +32,14 @@ module CalendariumRomanum
       prepare_solemnities
     end
 
-    # @return [Fixnum]
+    # @return [Integer]
     attr_reader :year
 
     class << self
       # Determines liturgical year for the given date
       #
       # @param date [Date]
-      # @return [Fixnum]
+      # @return [Integer]
       def liturgical_year(date)
         year = date.year
         temporale = Temporale.new year
@@ -64,8 +64,16 @@ module CalendariumRomanum
       # 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)
+      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)
@@ -218,20 +226,24 @@ module CalendariumRomanum
     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
@@ -251,8 +263,10 @@ module CalendariumRomanum
         nativity
       when Seasons::LENT
         ash_wednesday
+      when Seasons::TRIDUUM
+        good_friday
       when Seasons::EASTER
-        easter_sunday
+        easter_sunday + 1
       when Seasons::ORDINARY # ordinary time
         baptism_of_lord + 1
       else
@@ -272,11 +286,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
@@ -301,8 +317,8 @@ module CalendariumRomanum
     # @overload get(date)
     #   @param date [Date]
     # @overload get(month, day)
-    #   @param month [Fixnum]
-    #   @param day [Fixnum]
+    #   @param month [Integer]
+    #   @param day [Integer]
     # @return (see #[])
     def get(*args)
       if args.size == 1 && args[0].is_a?(Date)
@@ -318,6 +334,17 @@ module CalendariumRomanum
       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)
@@ -348,7 +375,7 @@ module CalendariumRomanum
       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
+      self.class.create_celebration title, rank, seas.colour, sunday: true
     end
 
     def ferial(date)