calendarium-romanum 0.2.1 → 0.7.0

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

@@ -0,0 +1,61 @@
+require 'roman-numerals'
+
+module CalendariumRomanum
+  # 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
+
+        case locale
+        when :cs
+          "#{number}."
+        when :en
+          english_ordinal(number)
+        when :fr
+          french_ordinal(number)
+        when :la, :it
+          RomanNumerals.to_roman number
+        else
+          number
+        end
+      end
+
+      private
+
+      def english_ordinal(number)
+        modulo = number % 10
+        modulo = 9 if number / 10 == 1
+
+        case modulo
+        when 1
+          "#{number}st"
+        when 2
+          "#{number}nd"
+        when 3
+          "#{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

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,33 +63,92 @@ 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
         @solemnities.delete date
       end
 
-      @days[date] = celebrations
+      @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
 
-    # 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)
+    # @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
+
+    # Retrieves {Celebration}s for the given date
+    #
+    # @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
@@ -66,24 +158,52 @@ module CalendariumRomanum
       end
 
       date = AbstractDate.new(month, day)
-      return @days[date] || []
+      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)
+      @solemnities.freeze
+      super
+    end
+
+    # @return [Boolean]
+    # @since 0.6.0
+    def ==(b)
+      self.class == b.class &&
+        days == b.days
+    end
+
+    protected
+
+    attr_reader :days
   end
 end