calendarium-romanum 0.3.0 → 0.7.1

data/lib/calendarium-romanum/enum.rb

@@ -1,12 +1,18 @@
 require 'forwardable'
 
 module CalendariumRomanum
-  # Utility class for definition of enumerated "types"
+  # Each subclass encapsulates a finite set of value objects.
+  #
+  # @abstract
   class Enum
     class << self
       extend Forwardable
 
-      def values(index_by: nil, &blk)
+      # @api private
+      # @param index_by
+      #   specifies which value objects' property contains
+      #   unique internal identifier for use with {.[]}
+      def values(index_by: nil)
         defined?(@indexed) && raise(RuntimeError.new('initialized repeatedly'))
 
         @indexed = {}
@@ -22,11 +28,24 @@ module CalendariumRomanum
         @indexed.freeze
       end
 
-      def all
-        @all
-      end
+      # Returns all contained value objects
+      #
+      # @return [Array]
+      attr_reader :all
 
+      # Enumerates contained value objects
+      #
+      # @!method each
+      #   @yield value object
+      #   @return [void]
       def_delegators :@all, :each
+
+      # Allows accessing contained value objects by their
+      # internal unique identifiers
+      #
+      # @!method [](identifier)
+      #   @param identifier
+      #   @return value object or nil
       def_delegators :@indexed, :[]
     end
   end

data/lib/calendarium-romanum/enums.rb

@@ -1,76 +1,142 @@
 module CalendariumRomanum
+  # Methods shared by most value objects defined by the gem
+  module ValueObjectInterface
+    # Machine-readable internal representation of the value
+    #
+    # @return [Symbol]
+    attr_reader :symbol
+    alias to_sym symbol
+
+    # Internationalized, human-readable name
+    #
+    # @return [String]
+    def name
+      I18n.t @i18n_key
+    end
 
+    # String representation of the contents for debugging purposes
+    #
+    # @return [String]
+    def to_s
+      "#<#{self.class.name} #{symbol}>"
+    end
+  end
+
+  # Represents a liturgical colour
   class Colour
+    include ValueObjectInterface
+
     def initialize(symbol)
       @symbol = symbol
+      @i18n_key = "colour.#{@symbol}"
     end
-
-    attr_reader :symbol
-    alias to_sym symbol
   end
 
+  # Standard set of liturgical colours
   class Colours < Enum
-    values do
+    GREEN = Colour.new(:green)
+    VIOLET = Colour.new(:violet)
+    WHITE = Colour.new(:white)
+    RED = Colour.new(:red)
+
+    values(index_by: :symbol) do
       [
-        GREEN = Colour.new(:green),
-        VIOLET = Colour.new(:violet),
-        WHITE = Colour.new(:white),
-        RED = Colour.new(:red)
+        GREEN,
+        VIOLET,
+        WHITE,
+        RED
       ]
     end
   end
 
+  # Convenience alias (American English spelling)
   Colors = Colours
 
+  # Liturgical season
   class Season
+    include ValueObjectInterface
+
+    # @param symbol [Symbol] internal identifier
+    # @param colour [Colour]
+    #   liturgical colour of the season's Sundays and ferials
     def initialize(symbol, colour)
       @symbol = symbol
       @colour = colour
+      @i18n_key = "temporale.season.#{@symbol}"
     end
 
-    attr_reader :symbol, :colour
-    alias to_sym symbol
+    # Liturgical colour of the season's Sundays and ferials
+    #
+    # @return [Colour]
+    attr_reader :colour
   end
 
+  # Standard set of liturgical seasons
   class Seasons < Enum
-    values do
+    ADVENT = Season.new(:advent, Colours::VIOLET)
+    CHRISTMAS = Season.new(:christmas, Colours::WHITE)
+    LENT = Season.new(:lent, Colours::VIOLET)
+    EASTER = Season.new(:easter, Colours::WHITE)
+    ORDINARY = Season.new(:ordinary, Colours::GREEN)
+
+    values(index_by: :symbol) do
       [
-        ADVENT = Season.new(:advent, Colours::VIOLET),
-        CHRISTMAS = Season.new(:christmas, Colours::WHITE),
-        LENT = Season.new(:lent, Colours::VIOLET),
-        EASTER = Season.new(:easter, Colours::WHITE),
-        ORDINARY = Season.new(:ordinary, Colours::GREEN)
+        ADVENT,
+        CHRISTMAS,
+        LENT,
+        EASTER,
+        ORDINARY,
       ]
     end
   end
 
-  LECTIONARY_CYCLES = [:A, :B, :C]
+  # Sunday lectionary cycles.
+  # Values returned by {Calendar#lectionary}
+  LECTIONARY_CYCLES = [:A, :B, :C].freeze
 
-  # ranks of celebrations
+  # Celebration ranks as specified in the Table of Liturgical Days
   class Ranks < 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
+    SOLEMNITY_PROPER  = Rank.new(1.4, 'rank.1_4', 'rank.short.solemnity')
+
+    FEAST_LORD_GENERAL  = Rank.new(2.5, 'rank.2_5', 'rank.short.feast')
+    SUNDAY_UNPRIVILEGED = Rank.new(2.6, 'rank.2_6', 'rank.short.sunday')
+    FEAST_GENERAL       = Rank.new(2.7, 'rank.2_7', 'rank.short.feast')
+    FEAST_PROPER        = Rank.new(2.8, 'rank.2_8', 'rank.short.feast')
+    FERIAL_PRIVILEGED   = Rank.new(2.9, 'rank.2_9', 'rank.short.ferial')
+
+    MEMORIAL_GENERAL  = Rank.new(3.10, 'rank.3_10', 'rank.short.memorial')
+    MEMORIAL_PROPER   = Rank.new(3.11, 'rank.3_11', 'rank.short.memorial')
+    MEMORIAL_OPTIONAL = Rank.new(3.12, 'rank.3_12', 'rank.short.memorial_opt')
+    FERIAL            = Rank.new(3.13, 'rank.3_13', 'rank.short.ferial')
+    # Not included as a celebration rank on it's own
+    # in the Table of Liturgical Days
+    COMMEMORATION     = Rank.new(4.0,  'rank.4_0', 'rank.short.commemoration')
+
     values(index_by: :priority) do
       # Values are at the same time references to sections
       # of the Table of Liturgical Days.
       # The lower value, the higher rank.
       [
-        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
-        SOLEMNITY_PROPER  = Rank.new(1.4, 'rank.1_4', 'rank.short.solemnity'),
-
-        FEAST_LORD_GENERAL  = Rank.new(2.5, 'rank.2_5', 'rank.short.feast'),
-        SUNDAY_UNPRIVILEGED = Rank.new(2.6, 'rank.2_6', 'rank.short.sunday'),
-        FEAST_GENERAL       = Rank.new(2.7, 'rank.2_7', 'rank.short.feast'),
-        FEAST_PROPER        = Rank.new(2.8, 'rank.2_8', 'rank.short.feast'),
-        FERIAL_PRIVILEGED   = Rank.new(2.9, 'rank.2_9', 'rank.short.ferial'),
-
-        MEMORIAL_GENERAL  = Rank.new(3.10, 'rank.3_10', 'rank.short.memorial'),
-        MEMORIAL_PROPER   = Rank.new(3.11, 'rank.3_11', 'rank.short.memorial'),
-        MEMORIAL_OPTIONAL = Rank.new(3.12, 'rank.3_12', 'rank.short.memorial_opt'),
-        FERIAL            = Rank.new(3.13, 'rank.3_13', 'rank.short.ferial'),
-        # not included as a celebration rank on it's own
-        # in the Table of Liturgical Days
-        COMMEMORATION     = Rank.new(4.0,  'rank.4_0', 'rank.short.commemoration')
+        TRIDUUM,
+        PRIMARY,
+        SOLEMNITY_GENERAL,
+        SOLEMNITY_PROPER,
+
+        FEAST_LORD_GENERAL,
+        SUNDAY_UNPRIVILEGED,
+        FEAST_GENERAL,
+        FEAST_PROPER,
+        FERIAL_PRIVILEGED,
+
+        MEMORIAL_GENERAL,
+        MEMORIAL_PROPER,
+        MEMORIAL_OPTIONAL,
+        FERIAL,
+
+        COMMEMORATION,
       ]
     end
   end

data/lib/calendarium-romanum/errors.rb

@@ -0,0 +1,4 @@
+module CalendariumRomanum
+  # Thrown by {SanctoraleLoader} on attempt to load invalid data
+  class InvalidDataError < RuntimeError; end
+end

data/lib/calendarium-romanum/ordinalizer.rb

@@ -1,9 +1,18 @@
 require 'roman-numerals'
 
 module CalendariumRomanum
-  # Knows how to produce localized ordinals
+  # Knows how to produce localized ordinals.
+  #
+  # Used by {Temporale} for building names of Sundays and ferials.
   class Ordinalizer
     class << self
+      # @param number [Fixnum] 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]
+      #   ordinal, or unchanged +number+ if +Ordinalizer+ cannot
+      #   build ordinals for the given locale
       def ordinal(number, locale: nil)
         locale ||= I18n.locale
 
@@ -12,7 +21,8 @@ module CalendariumRomanum
           "#{number}."
         when :en
           english_ordinal(number)
-        # when :it # TODO
+        when :fr
+          french_ordinal(number)
         when :la, :it
           RomanNumerals.to_roman number
         else
@@ -20,18 +30,32 @@ module CalendariumRomanum
         end
       end
 
+      private
+
       def english_ordinal(number)
-        case number
+        modulo = number % 10
+        modulo = 9 if number / 10 == 1
+
+        case modulo
         when 1
-          '1st'
+          "#{number}st"
         when 2
-          '2nd'
+          "#{number}nd"
         when 3
-          '3rd'
+          "#{number}rd"
         else
           "#{number}th"
         end
       end
+
+      def french_ordinal(number)
+        case number
+        when 1
+          '1er'
+        else
+          "#{number}ème"
+        end
+      end
     end
   end
 end

data/lib/calendarium-romanum/perpetual_calendar.rb

@@ -0,0 +1,97 @@
+module CalendariumRomanum
+  # Has mostly the same public interface as {Calendar},
+  # but represents a "perpetual" calendar, not a calendar
+  # for a single year, thus allowing the client code
+  # to query for liturgical data of any day, without bothering
+  # about boundaries of liturgical years.
+  #
+  # Internally builds {Calendar} instances as needed
+  # and delegates method calls to them.
+  #
+  # @since 0.4.0
+  class PerpetualCalendar
+    # @param sanctorale [Sanctorale, nil]
+    # @param temporale_factory [Proc, nil]
+    #   +Proc+ receiving a single parameter - year - and returning
+    #   a {Temporale} instance.
+    # @param temporale_options [Hash, nil]
+    #   +Hash+ of arguments for {Temporale#initialize}.
+    #   +temporale_factory+ and +temporale_options+ are mutually
+    #   exclusive - pass either (or none) of them, never both.
+    # @param cache [Hash]
+    #   object to be used as internal cache of {Calendar} instances -
+    #   anything exposing +#[]=+ and +#[]+ and "behaving mostly like
+    #   a +Hash+" will work.
+    #   There's no need to pass it unless you want to have control
+    #   over the cache. That may be sometimes useful
+    #   in order to prevent a long-lived
+    #   +PerpetualCalendar+ instance flooding the memory
+    #   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: {})
+      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)
+
+      @cache = cache
+    end
+
+    # @return [Day]
+    # @see Calendar#day
+    def day(*args)
+      calendar_for(*args).day(*args)
+    end
+
+    # @return [Day, Array<Day>]
+    # @see Calendar#[]
+    # @since 0.6.0
+    def [](arg)
+      if arg.is_a? Range
+        return arg.collect do |date|
+          calendar_for(date).day(date)
+        end
+      end
+
+      day(arg)
+    end
+
+    # Returns a {Calendar} instance for the liturgical year containing
+    # the specified day
+    #
+    # Parameters like {Calendar#day}
+    #
+    # @return [Calendar]
+    def calendar_for(*args)
+      date = Calendar.mk_date(*args)
+      year = Temporale.liturgical_year date
+      calendar_instance year
+    end
+
+    # Returns a Calendar instance for the specified liturgical year
+    #
+    # @param year [Fixnum]
+    # @return [Calendar]
+    def calendar_for_year(year)
+      calendar_instance year
+    end
+
+    private
+
+    def build_temporale_factory(temporale_options)
+      temporale_options ||= {}
+      lambda {|year| Temporale.new(year, **temporale_options) }
+    end
+
+    def calendar_instance(year)
+      if @cache.has_key? year
+        @cache[year]
+      else
+        @cache[year] = Calendar.new(year, @sanctorale, @temporale_factory.call(year))
+      end
+    end
+  end
+end

data/lib/calendarium-romanum/rank.rb

@@ -1,40 +1,77 @@
 module CalendariumRomanum
+  # Celebration rank
   class Rank
     include Comparable
 
-    def initialize(priority=nil, desc=nil, short_desc=nil)
+    # @param priority [Float, nil] number in the Table of Liturgical Days
+    # @param desc [String, nil]
+    #   full description (translation string identifier)
+    # @param short_desc [String, nil]
+    #   short rank name (translation string identifier)
+    def initialize(priority = nil, desc = nil, short_desc = nil)
       @priority = priority
       @desc = desc
       @short_desc = short_desc
     end
 
+    # @return [Float, nil]
     attr_reader :priority
-    alias_method :to_f, :priority
+    alias to_f priority
 
+    # Full description - internationalized human-readable string.
+    #
+    # @return [String, nil]
     def desc
       @desc && I18n.t(@desc)
     end
 
-    alias_method :to_s, :desc
+    # String representation mostly for debugging purposes.
+    #
+    # @return [String]
+    def to_s
+      # 'desc' instead of '@desc' is intentional -
+      # for a good reason we don't present contents of an instance
+      # variable but result of an instance method
+      "#<#{self.class.name} @priority=#{priority} desc=#{desc.inspect}>"
+    end
 
+    # Short name - internationalized human-readable string.
+    #
+    # @return [String, nil]
     def short_desc
       @short_desc && I18n.t(@short_desc)
     end
 
-    def <=>(b)
-      b.priority <=> self.priority
+    def <=>(other)
+      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
+
+    # @return [Boolean]
     def feast?
       priority.to_i == 2
     end
 
+    # @return [Boolean]
     def memorial?
-      priority.to_i == 3
+      priority.to_i == 3 && priority <= 3.12
+    end
+
+    # @return [Boolean]
+    # @since 0.6.0
+    def ferial?
+      self == Ranks::FERIAL ||
+        self == Ranks::FERIAL_PRIVILEGED
     end
   end
 end