calendarium-romanum 0.2.1 → 0.7.0

data/lib/calendarium-romanum/cr.rb

@@ -0,0 +1,16 @@
+require 'calendarium-romanum'
+
+# The module name {CalendariumRomanum} is quite long,
+# hence constant +CR+ is provided as a convenient shortcut.
+# It is _not_ loaded by +require 'calendarium-romanum'+,
+# must be required explicitly +require 'calendarium-romanum/cr'+ -
+# because there's a good chance
+# that the short constant name clashes with a constant
+# defined by some other code.
+#
+# @example
+#   require 'calendarium-romanum/cr'
+#
+#   calendar = CR::Calendar.new 2000
+# @since 0.7.0
+CR = CalendariumRomanum

data/lib/calendarium-romanum/data.rb

@@ -1,8 +1,16 @@
 module CalendariumRomanum
-  # allows easy access to the bundled data files
+  # Allows easy access to bundled data files
+  #
+  # @example
+  #   sanctorale = CalendariumRomanum::Data::GENERAL_ROMAN_LATIN.load
   class Data < 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,32 +18,52 @@ 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_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_ITALIAN = SanctoraleFile.new('universal-it.txt'),
-        CZECH = SanctoraleFile.new('czech-cs.txt')
+        GENERAL_ROMAN_LATIN,
+        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

@@ -2,55 +2,156 @@ 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 [Fixnum, 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 [Fixnum]
     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 [Fixnum]
     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 of the following day if it has first vespers
+    # {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 &&
+        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
 
-    def initialize(title='', rank=Ranks::FERIAL, colour=Colours::GREEN)
+    # @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)
       @title = title
       @rank = rank
       @colour = colour
+      @symbol = symbol
+      @date = date
+      @cycle = cycle
     end
 
+    # @return [Rank]
     attr_reader :rank
-    def_delegators :@rank, :solemnity?, :feast?, :memorial?
 
+    # @!method solemnity?
+    #   @return [Boolean]
+    # @!method feast?
+    #   @return [Boolean]
+    # @!method memorial?
+    #   @return [Boolean]
+    # @!method sunday?
+    #   @return [Boolean]
+    #   @since 0.6.0
+    # @!method ferial?
+    #   @return [Boolean]
+    #   @since 0.6.0
+    def_delegators :@rank, :solemnity?, :feast?, :memorial?, :sunday?, :ferial?
+
+    # Feast title/name
+    #
+    # @return [String]
     def title
       if @title.respond_to? :call
         @title.call
@@ -59,7 +160,85 @@ module CalendariumRomanum
       end
     end
 
+    # Liturgical colour
+    #
+    # @return [Colour]
     attr_reader :colour
-    alias_method :color, :colour
+    alias color 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
+
+    # 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)
+      self.class.new(
+        title || self.title,
+        rank || self.rank,
+        colour || color || self.colour,
+        symbol || self.symbol,
+        date || self.date,
+        cycle || self.cycle,
+      )
+    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,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,57 +1,143 @@
 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
+
+  # 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,
+        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
-    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 = :advent,
-        CHRISTMAS = :christmas,
-        LENT = :lent,
-        EASTER = :easter,
-        ORDINARY = :ordinary,
-        # is Triduum Sacrum a special season? For now I count Friday and Saturday
-        # to the Lent, Sunday to the Easter time
+        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')
-      ]
-    end
-  end
+        TRIDUUM,
+        PRIMARY,
+        SOLEMNITY_GENERAL,
+        SOLEMNITY_PROPER,
 
-  class Colours < Enum
-    values do
-      [
-        GREEN = :green,
-        VIOLET = :violet,
-        WHITE = :white,
-        RED = :red
+        FEAST_LORD_GENERAL,
+        SUNDAY_UNPRIVILEGED,
+        FEAST_GENERAL,
+        FEAST_PROPER,
+        FERIAL_PRIVILEGED,
+
+        MEMORIAL_GENERAL,
+        MEMORIAL_PROPER,
+        MEMORIAL_OPTIONAL,
+        FERIAL,
+
+        COMMEMORATION,
       ]
     end
   end
-
-  Colors = Colours
 end