calendarium-romanum 0.4.0 → 0.8.0

data/lib/calendarium-romanum/data.rb

@@ -1,8 +1,17 @@
 module CalendariumRomanum
-  # allows easy access to bundled data files
-  class Data < Enum
+  # Allows easy access to bundled data files
+  #
+  # @example
+  #   sanctorale = CalendariumRomanum::Data::GENERAL_ROMAN_LATIN.load
+  module Data
+    extend Enum
 
     class SanctoraleFile
+      # This class is not intended to be initialized by client code -
+      # it's sole purpose is to provide functionality for easy
+      # loading of the bundled sanctorale data files.
+      #
+      # @api private
       def initialize(base_name)
         @siglum = base_name.sub(/\.txt$/, '')
         @path = File.expand_path('../../data/' + base_name, File.dirname(__FILE__))
@@ -10,33 +19,54 @@ module CalendariumRomanum
 
       attr_reader :siglum, :path
 
+      # Load the data file
+      #
+      # @return [Sanctorale]
       def load
-        SanctoraleLoader.new.load_from_file(@path)
+        SanctoraleLoader.new.load_from_file(path)
+      end
+
+      # Load the data file and all it's parents
+      #
+      # @return [Sanctorale]
+      # @since 0.7.0
+      def load_with_parents
+        SanctoraleFactory.load_with_parents(path)
       end
     end
 
+    GENERAL_ROMAN_LATIN = SanctoraleFile.new('universal-la.txt')
+    GENERAL_ROMAN_LATIN_1969 = SanctoraleFile.new('universal-1969-la.txt')
+    GENERAL_ROMAN_ENGLISH = SanctoraleFile.new('universal-en.txt')
+    GENERAL_ROMAN_FRENCH = SanctoraleFile.new('universal-fr.txt')
+    GENERAL_ROMAN_ITALIAN = SanctoraleFile.new('universal-it.txt')
+    GENERAL_ROMAN_SPANISH = SanctoraleFile.new('universal-es.txt')
+    CZECH = SanctoraleFile.new('czech-cs.txt')
+
     values(index_by: :siglum) do
       # only calendars of broader interest have constants defined
       [
-        GENERAL_ROMAN_LATIN = SanctoraleFile.new('universal-la.txt'),
-        GENERAL_ROMAN_ENGLISH = SanctoraleFile.new('universal-en.txt'),
-        GENERAL_ROMAN_FRENCH = SanctoraleFile.new('universal-fr.txt'),
-        GENERAL_ROMAN_ITALIAN = SanctoraleFile.new('universal-it.txt'),
-        CZECH = SanctoraleFile.new('czech-cs.txt')
+        GENERAL_ROMAN_LATIN,
+        GENERAL_ROMAN_LATIN_1969,
+        GENERAL_ROMAN_ENGLISH,
+        GENERAL_ROMAN_FRENCH,
+        GENERAL_ROMAN_ITALIAN,
+        GENERAL_ROMAN_SPANISH,
+        CZECH,
       ] \
       +
-      %w(
-      czech-brno-cs.txt
-      czech-budejovice-cs.txt
-      czech-cechy-cs.txt
-      czech-hradec-cs.txt
-      czech-litomerice-cs.txt
-      czech-morava-cs.txt
-      czech-olomouc-cs.txt
-      czech-ostrava-cs.txt
-      czech-plzen-cs.txt
-      czech-praha-cs.txt
-      ).collect {|basename| SanctoraleFile.new(basename) }
+        %w(
+          czech-brno-cs.txt
+          czech-budejovice-cs.txt
+          czech-cechy-cs.txt
+          czech-hradec-cs.txt
+          czech-litomerice-cs.txt
+          czech-morava-cs.txt
+          czech-olomouc-cs.txt
+          czech-ostrava-cs.txt
+          czech-plzen-cs.txt
+          czech-praha-cs.txt
+        ).collect {|basename| SanctoraleFile.new(basename) }
     end
   end
 end

data/lib/calendarium-romanum/day.rb

@@ -1,61 +1,172 @@
-require 'forwardable'
-
 module CalendariumRomanum
 
-  # information on one particular day of the liturgical year
+  # Information on one particular day of the liturgical year
   class Day
-    def initialize(args={})
-      %i(date season season_week celebrations).each do |a|
-        if args.include? a
-          instance_variable_set "@#{a}", args.delete(a)
-        end
-      end
-
-      unless args.empty?
-        raise ArgumentError.new "Unexpected arguments #{args.keys.join(', ')}"
-      end
+    # Note: despite of all constructor arguments being nullable,
+    # instances returned by {Calendar} always have all of them set,
+    # the only exception being +vespers+.
+    #
+    # @param date [Date, nil]
+    # @param season [Season, nil]
+    # @param season_week [Integer, nil]
+    # @param celebrations [Array<Celebration>, nil]
+    # @param vespers [Celebration, nil]
+    def initialize(date: nil, season: nil, season_week: nil, celebrations: nil, vespers: nil)
+      @date = date
+      @season = season
+      @season_week = season_week
+      @celebrations = celebrations ? celebrations.dup : []
+      @vespers = vespers
     end
 
+    # @return [Date]
     attr_reader :date
 
+    # Weekday as integer (Sunday is 0)
+    #
+    # @return [Integer]
     def weekday
       date.wday
     end
 
-    # one of the Seasons (Symbol)
+    # Weekday as internationalized string
+    #
+    # @return [String]
+    # @since 0.7.0
+    def weekday_name
+      I18n.t(date.wday, scope: 'weekday')
+    end
+
+    # @return [Season]
     attr_reader :season
 
-    # week of the season (Integer)
+    # Week of the season
+    #
+    # @return [Integer]
     attr_reader :season_week
 
-    # an Array of Celebrations, possibly empty
+    # List of celebrations for the given day.
+    #
+    # In tests and other "less-standard" situations the array
+    # may be empty, but it's never empty for instances
+    # returned by {Calendar}.
+    #
+    # @return [Array<Celebration>]
     attr_reader :celebrations
 
+    # {Celebration} whose first Vespers are celebrated
+    # in place of Vespers of the day's {Celebration}(s).
+    # Please note that {Calendar} by default _doesn't_ populate
+    # Vespers, - it's an opt-in feature
+    # (see {Calendar#initialize}, {Calendar#populates_vespers?},
+    # {Calendar#day}).
+    #
+    # @return [Celebration, nil]
+    # @since 0.5.0
+    attr_reader :vespers
+
     def ==(other)
       self.class == other.class &&
         date == other.date &&
         season == other.season &&
         season_week == other.season_week &&
-        celebrations == other.celebrations
+        celebrations == other.celebrations &&
+        vespers == other.vespers
+    end
+
+    # Are the day's Vespers suppressed in favour of first Vespers
+    # of a Sunday or solemnity?
+    #
+    # @return [Boolean]
+    def vespers_from_following?
+      !vespers.nil?
+    end
+
+    # String representation of the instance listing it's contents.
+    # Intended mostly for debugging purposes.
+    #
+    # @return [String]
+    # @since 0.7.0
+    def to_s
+      celebrations_string = '['
+      celebrations.each do |c|
+        celebrations_string << c.to_s + ', '
+      end
+      celebrations_string = celebrations_string.chomp(', ') << ']'
+      "#<#{self.class.name} @date=#{date} @season=#{season} @season_week=#{season_week} celebrations=#{celebrations_string} vespers=#{vespers.inspect}>"
     end
   end
 
-  # information on one particular celebration of the liturgical year
+  # One particular celebration of the liturgical year
   # (like a Sunday, feast or memorial);
-  # some days have no (ferial office is used), some have one,
-  # some have more among which one may and may not be chosen
+  # some days have one,
+  # some have more among which one is to be chosen
   class Celebration
-    extend Forwardable
+    include RankPredicates
+
+    # All arguments can be passed either as positional or keyword arguments.
+    # In case of conflict keyword arguments win.
+    # @example
+    #   Celebration.new('Lost title', title: 'Winning title') # will have title 'Winning title'
+    #
+    # @param title [String|Proc]
+    #   Celebration title/name.
+    #   If a +Proc+ is passed, it is expected not to receive
+    #   arguments and to return a +String+.
+    #   (Used for celebration titles which have to be
+    #   internationalizable - the +Proc+ is called whenever
+    #   {#title} is invoked, which allows the value to vary
+    #   depending e.g. on state of the +Proc+ or some
+    #   global setting - like +I18n.locale+ - it may access.)
+    # @param rank [Rank] Celebration rank
+    # @param colour [Colour] Liturgical colour
+    # @param symbol [Symbol, nil]
+    #   Unique machine-readable identifier of the celebration
+    # @param date [AbstractDate, nil]
+    #   Normal fixed date of the celebration
+    # @param cycle [:sanctorale, :temporale]
+    #   Cycle the celebration belongs to
+    def initialize(title = '', rank = Ranks::FERIAL, colour = Colours::GREEN, symbol = nil, date = nil, cycle = :sanctorale, sunday = false, **kwargs)
+      @title = kwargs.delete(:title) || title
+      @rank = kwargs.delete(:rank) || rank
+      @colour = kwargs.delete(:colour) || kwargs.delete(:color) || colour
+      @symbol = kwargs.delete(:symbol) || symbol
+      @date = kwargs.delete(:date) || date
+      @cycle = kwargs.delete(:cycle) || cycle
+      @sunday = kwargs.delete(:sunday) || sunday
+
+      unless kwargs.empty?
+        raise ArgumentError.new('Unexpected keyword arguments: ' + kwargs.keys.inspect)
+      end
+
+      if @sunday && ![Ranks::SUNDAY_UNPRIVILEGED, Ranks::PRIMARY].include?(@rank)
+        raise ArgumentError.new("Rank #{@rank} cannot be Sunday")
+      end
+    end
 
-    def initialize(title='', rank=Ranks::FERIAL, colour=Colours::GREEN)
-      @title = title
-      @rank = rank
-      @colour = colour
+    # Build a new instance using the receiver's attributes
+    # for all properties for which (a non-nil) value was not passed.
+    #
+    # @return [Celebration]
+    # @since 0.5.0
+    def change(title: nil, rank: nil, colour: nil, color: nil, symbol: nil, date: nil, cycle: nil, sunday: nil)
+      self.class.new(
+        title: title || self.title,
+        rank: rank || self.rank,
+        colour: colour || color || self.colour,
+        symbol: symbol || self.symbol,
+        date: date || self.date,
+        cycle: cycle || self.cycle,
+        sunday: sunday || @sunday
+      )
     end
 
+    # @return [Rank]
     attr_reader :rank
-    def_delegators :@rank, :solemnity?, :feast?, :memorial?
 
+    # Feast title/name
+    #
+    # @return [String]
     def title
       if @title.respond_to? :call
         @title.call
@@ -64,14 +175,79 @@ module CalendariumRomanum
       end
     end
 
+    # Liturgical colour
+    #
+    # @return [Colour]
     attr_reader :colour
-    alias_method :color, :colour
+    alias color colour
 
-    def ==(other)
-      self.class == other.class &&
-        title == other.title &&
-        rank == other.rank &&
-        colour == other.colour
+    # Symbol uniquely identifying the celebration
+    #
+    # @return [Symbol, nil]
+    # @since 0.5.0
+    attr_reader :symbol
+
+    # Usual date of the celebration.
+    #
+    # Only set for celebrations with fixed date.
+    # (Only) In case of solemnities it may happen that
+    # {Celebration#date} differs from {Day#date} due to
+    # transfer of an impeded solemnity.
+    #
+    # @return [AbstractDate, nil]
+    # @since 0.6.0
+    attr_reader :date
+
+    # Describes the celebration as belonging either to the
+    # temporale or sanctorale cycle
+    #
+    # @return [:sanctorale, :temporale]
+    # @since 0.6.0
+    attr_reader :cycle
+
+    def ==(b)
+      self.class == b.class &&
+        title == b.title &&
+        rank == b.rank &&
+        colour == b.colour &&
+        symbol == b.symbol &&
+        date == b.date &&
+        cycle == b.cycle
+    end
+
+    # Does the celebration belong to the temporale cycle?
+    #
+    # @return [Boolean]
+    # @since 0.6.0
+    def temporale?
+      cycle == :temporale
+    end
+
+    # Does the celebration belong to the sanctorale cycle?
+    #
+    # @return [Boolean]
+    # @since 0.6.0
+    def sanctorale?
+      cycle == :sanctorale
+    end
+
+    # Is the celebration a Sunday?
+    #
+    # Please note that for "privileged Sundays" true is returned, while {Rank#sunday?}
+    # returns false (because not all celebrations of that rank are Sundays).
+    #
+    # @return [Boolean]
+    def sunday?
+      rank.sunday? || @sunday
+    end
+
+    # String representation of the object's contents
+    # (not very pretty, intended mostly for development inspections).
+    #
+    # @return [String]
+    # @since 0.7.0
+    def to_s
+      "#<#{self.class.name} @title=\"#{title}\" @rank=#{rank} @colour=#{colour} symbol=#{symbol.inspect} date=#{date.inspect} cycle=#{cycle.inspect}>"
     end
   end
 end

data/lib/calendarium-romanum/enum.rb

@@ -1,33 +1,50 @@
 require 'forwardable'
 
 module CalendariumRomanum
-  # Utility class for definition of enumerated "types"
-  class Enum
-    class << self
-      extend Forwardable
-
-      def values(index_by: nil, &blk)
-        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
-      end
-
-      def all
-        @all
+  # 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'))
+
+      @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
 
-      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