calendarium-romanum 0.5.0 → 0.9.0

data/lib/calendarium-romanum/enum.rb

@@ -1,31 +1,48 @@
 require 'forwardable'
 
 module CalendariumRomanum
-  # Utility class for definition of enumerated "types"
-  class Enum
-    class << self
-      extend Forwardable
-
-      def values(index_by: nil)
-        defined?(@indexed) && raise(RuntimeError.new('initialized repeatedly'))
-
-        @indexed = {}
-        @all = yield.freeze
-
-        @all.each_with_index do |val, i|
-          val.freeze
-
-          key = index_by ? val.public_send(index_by) : i
-          @indexed[key] = val
-        end
-
-        @indexed.freeze
+  # Each Enum encapsulates a finite set of value objects.
+  #
+  # @api private
+  module Enum
+    extend Forwardable
+
+    # @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'))
+
+      @all = yield.freeze
+      @all.each &:freeze
+
+      @indexed = {}
+      @all.each_with_index do |val, i|
+        key = index_by ? val.public_send(index_by) : i
+        @indexed[key] = val
       end
-
-      attr_reader :all
-
-      def_delegators :@all, :each
-      def_delegators :@indexed, :[]
+      @indexed.freeze
     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,87 +1,171 @@
 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
+  end
 
-    attr_reader :symbol
-    alias to_sym symbol
+  # Standard set of liturgical colours
+  module Colours
+    extend Enum
 
-    def name
-      I18n.t @i18n_key
-    end
-  end
+    GREEN = Colour.new(:green)
+    VIOLET = Colour.new(:violet)
+    WHITE = Colour.new(:white)
+    RED = Colour.new(:red)
 
-  class Colours < Enum
     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
-
-    def name
-      I18n.t @i18n_key
-    end
+    # Liturgical colour of the season's Sundays and ferials
+    #
+    # May be +nil+ if there is no single colour.
+    #
+    # @return [Colour, nil]
+    attr_reader :colour
   end
 
-  class Seasons < Enum
+  # Standard set of liturgical seasons
+  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)
+
     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,
+        TRIDUUM,
+        EASTER,
+        ORDINARY,
       ]
     end
   end
 
+  # Sunday lectionary cycles.
+  # Values returned by {Calendar#lectionary}
   LECTIONARY_CYCLES = [:A, :B, :C].freeze
 
-  # ranks of celebrations
-  class Ranks < Enum
+  # Celebration ranks as specified in the Table of Liturgical Days
+  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
+    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
+
+  # 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 the current module
+  #
+  # @since 0.8.0
+  module Constants
+    include Colours
+    include Seasons
+    include Ranks
+  end
 end

data/lib/calendarium-romanum/errors.rb

@@ -1,4 +1,4 @@
 module CalendariumRomanum
-  # attempt to load invalid calendar data
+  # 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 [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, Integer]
+      #   ordinal, or unchanged +number+ if +Ordinalizer+ cannot
+      #   build ordinals for the given locale
       def ordinal(number, locale: nil)
         locale ||= I18n.locale
 

data/lib/calendarium-romanum/perpetual_calendar.rb

@@ -1,32 +1,83 @@
 module CalendariumRomanum
-  # When you want to query a calendar without caring about
-  # civil and liturgical years and Calendar instances
+  # 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
-    def initialize(sanctorale: nil, temporale_factory: nil, temporale_options: nil, cache: {})
+    # @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 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
+    #   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, 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
 
-    # returns a resolved Day
+    # @return [Day]
+    # @see Calendar#day
     def day(*args)
       calendar_for(*args).day(*args)
     end
 
-    # returns a Calendar instance for the liturgical year containing
+    # @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
+    # Returns a Calendar instance for the specified liturgical year
+    #
+    # @param year [Integer]
+    # @return [Calendar]
     def calendar_for_year(year)
       calendar_instance year
     end
@@ -42,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,22 +1,44 @@
 module CalendariumRomanum
+  # Celebration rank
   class Rank
+    include RankPredicates
     include Comparable
 
+    # @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 to_f priority
 
+    # Full description - internationalized human-readable string.
+    #
+    # @return [String, nil]
     def desc
       @desc && I18n.t(@desc)
     end
 
-    alias 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
@@ -25,16 +47,25 @@ module CalendariumRomanum
       other.priority <=> priority
     end
 
-    def solemnity?
-      priority.to_i == 1
-    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
 
-    def feast?
-      priority.to_i == 2
+      all[index - 1]
     end
 
-    def memorial?
-      priority.to_i == 3 && priority <= 3.12
+    private
+
+    # Required by the {RankPredicates} mixin
+    def rank
+      self
     end
   end
 end