calendarium-romanum 0.6.0 → 0.7.0

data/lib/calendarium-romanum/enum.rb

@@ -1,11 +1,17 @@
 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
 
+      # @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'))
 
@@ -22,9 +28,24 @@ module CalendariumRomanum
         @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,17 +1,28 @@
 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
 
@@ -21,70 +32,111 @@ module CalendariumRomanum
     end
   end
 
+  # Standard set of liturgical colours
   class Colours < Enum
+    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
 
+    # Liturgical colour of the season's Sundays and ferials
+    #
+    # @return [Colour]
     attr_reader :colour
   end
 
+  # Standard set of liturgical seasons
   class Seasons < Enum
+    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
 
+  # 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

@@ -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 [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
 

data/lib/calendarium-romanum/perpetual_calendar.rb

@@ -1,7 +1,34 @@
 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
+    # @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')
@@ -13,11 +40,15 @@ module CalendariumRomanum
       @cache = cache
     end
 
-    # returns a resolved Day
+    # @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|
@@ -28,15 +59,22 @@ module CalendariumRomanum
       day(arg)
     end
 
-    # returns a Calendar instance for the liturgical year containing
+    # 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 [Fixnum]
+    # @return [Calendar]
     def calendar_for_year(year)
       calendar_instance year
     end

data/lib/calendarium-romanum/rank.rb

@@ -1,20 +1,33 @@
 module CalendariumRomanum
+  # Celebration rank
   class Rank
     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
 
+    # 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
@@ -22,6 +35,9 @@ module CalendariumRomanum
       "#<#{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
@@ -30,22 +46,29 @@ 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
 
+    # @return [Boolean]
     def feast?
       priority.to_i == 2
     end
 
+    # @return [Boolean]
     def memorial?
       priority.to_i == 3 && priority <= 3.12
     end
 
+    # @return [Boolean]
+    # @since 0.6.0
     def ferial?
       self == Ranks::FERIAL ||
         self == Ranks::FERIAL_PRIVILEGED

data/lib/calendarium-romanum/sanctorale.rb

@@ -1,27 +1,60 @@
+require 'set'
+
 module CalendariumRomanum
 
-  # knows the fixed-date celebrations
+  # One of the two main {Calendar} components.
+  # Contains celebrations with fixed date, mostly feasts of saints.
+  #
+  # Basically a mapping {AbstractDate} => Array<{Celebration}>
+  # additionally enforcing some constraints:
+  #
+  # - for a given {AbstractDate} there may be multiple {Celebration}s,
+  #   but only if all of them are in the rank of an optional
+  #   memorial
+  # - {Celebration#symbol} must be unique in the whole set of
+  #   contained celebrations
   class Sanctorale
 
     def initialize
       @days = {}
-
       @solemnities = {}
+      @symbols = Set.new
+      @metadata = nil
     end
 
+    # Content subset - only {Celebration}s in the rank(s) of solemnity.
+    #
+    # @return [Hash<AbstractDate=>Celebration>]
     attr_reader :solemnities
 
+    # Sanctorale metadata.
+    #
+    # Data files may contain YAML front matter.
+    # If provided, it's loaded by {SanctoraleLoader} and
+    # stored in this property.
+    # All data files bundled in the gem (see {Data}) have YAML
+    # front matter which is a Hash with a few standardized keys.
+    # While YAML also supports top-level content of other types,
+    # sanctorale data authors should stick to the convention
+    # of using Hash as the top-level data structure of their
+    # front matters.
+    #
+    # @return [Hash, nil]
+    # @since 0.7.0
+    attr_accessor :metadata
+
+    # Adds a new {Celebration}
+    #
+    # @param month [Fixnum]
+    # @param day [Fixnum]
+    # @param celebration [Celebration]
+    # @return [void]
+    # @raise [ArgumentError]
+    #   when performing the operation would break the object's invariant
     def add(month, day, celebration)
       date = AbstractDate.new(month, day)
-      unless @days.has_key? date
-        @days[date] = []
-      end
 
-      if celebration.solemnity?
-        @solemnities[date] = celebration
-      end
-
-      unless @days[date].empty?
+      unless @days[date].nil? || @days[date].empty?
         present = @days[date][0]
         if present.rank != Ranks::MEMORIAL_OPTIONAL
           raise ArgumentError.new("On #{date} there is already a #{present.rank}. No more celebrations can be added.")
@@ -30,13 +63,51 @@ module CalendariumRomanum
         end
       end
 
+      unless celebration.symbol.nil?
+        if @symbols.include? celebration.symbol
+          raise ArgumentError.new("Attempted to add Celebration with duplicate symbol #{celebration.symbol.inspect}")
+        end
+
+        @symbols << celebration.symbol
+      end
+
+      unless @days.has_key? date
+        @days[date] = []
+      end
+
+      if celebration.solemnity?
+        @solemnities[date] = celebration
+      end
+
       @days[date] << celebration
     end
 
-    # replaces content of the given day by given celebrations
+    # Replaces content of the given day by given {Celebration}s
+    #
+    # @param month [Fixnum]
+    # @param day [Fixnum]
+    # @param celebrations [Array<Celebration>]
+    # @return [void]
+    # @raise [ArgumentError]
+    #   when performing the operation would break the object's invariant
     def replace(month, day, celebrations)
       date = AbstractDate.new(month, day)
 
+      symbols_without_day = @symbols
+      unless @days[date].nil?
+        old_symbols = @days[date].collect(&:symbol).compact
+        symbols_without_day = @symbols - old_symbols
+      end
+
+      new_symbols = celebrations.collect(&:symbol).compact
+      duplicate = symbols_without_day.intersection new_symbols
+      unless duplicate.empty?
+        raise ArgumentError.new("Attempted to add Celebrations with duplicate symbols #{duplicate.to_a.inspect}")
+      end
+
+      @symbols = symbols_without_day
+      @symbols.merge new_symbols
+
       if celebrations.first.solemnity?
         @solemnities[date] = celebrations.first
       elsif @solemnities.has_key? date
@@ -46,22 +117,38 @@ module CalendariumRomanum
       @days[date] = celebrations.dup
     end
 
-    # adds all Celebrations from another instance
-    def update(sanctorale)
-      sanctorale.each_day do |date, celebrations|
+    # Updates the receiver with {Celebration}s from another instance.
+    #
+    # For each date contained in +other+ the content of +self+
+    # is _replaced_ by that of +other+.
+    #
+    # @param other [Sanctorale]
+    # @return [void]
+    # @raise (see #replace)
+    def update(other)
+      other.each_day do |date, celebrations|
         replace date.month, date.day, celebrations
       end
     end
 
+    # Retrieves {Celebration}s for the given date
+    #
+    # @param date [AbstractDate, Date]
+    # @return [Array<Celebration>] (may be empty)
+    # @since 0.6.0
     def [](date)
       adate = date.is_a?(AbstractDate) ? date : AbstractDate.from_date(date)
       @days[adate] || []
     end
 
-    # returns an Array with one or more Celebrations
-    # scheduled for the given day
+    # Retrieves {Celebration}s for the given date
     #
-    # expected arguments: Date or two Integers (month, day)
+    # @overload get(date)
+    #   @param date[AbstractDate, 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)
         month = args[0].month
@@ -74,23 +161,33 @@ module CalendariumRomanum
       self[date]
     end
 
-    # for each day for which an entry is available
-    # yields an AbstractDate and an Array of Celebrations
+    # Enumerates dates for which any {Celebration}s are available
+    #
+    # @yield [AbstractDate, Array<Celebration>] the array is never empty
+    # @return [void, Enumerator] if called without a block, returns +Enumerator+
     def each_day
+      return to_enum(__method__) unless block_given?
+
       @days.each_pair do |date, celebrations|
         yield date, celebrations
       end
     end
 
-    # returns count of the _days_ with celebrations filled
+    # Returns count of _days_ with {Celebration}s filled
+    #
+    # @return [Fixnum]
     def size
       @days.size
     end
 
+    # It is empty if it doesn't contain any {Celebration}
+    #
+    # @return [Boolean]
     def empty?
       @days.empty?
     end
 
+    # Freezes the instance
     def freeze
       @days.freeze
       @days.values.each(&:freeze)
@@ -98,6 +195,8 @@ module CalendariumRomanum
       super
     end
 
+    # @return [Boolean]
+    # @since 0.6.0
     def ==(b)
       self.class == b.class &&
         days == b.days