calendarium-romanum 0.5.0 → 0.9.0

data/lib/calendarium-romanum/cli/comparator.rb

@@ -0,0 +1,83 @@
+require 'set'
+
+module CalendariumRomanum
+  class CLI
+    # Compares two sanctorale data files, reports differences.
+    #
+    # @api private
+    class Comparator
+      include Helper
+
+      SUPPORTED_PROPERTIES = %i(rank colour symbol title)
+      DEFAULT_PROPERTIES = SUPPORTED_PROPERTIES - %i(title)
+
+      def initialize(properties = DEFAULT_PROPERTIES)
+        unless Set.new(properties) <= Set.new(SUPPORTED_PROPERTIES)
+          raise ArgumentError.new("Unsupported properties specified: #{properties} Only #{SUPPORTED_PROPERTIES} are supported")
+        end
+
+        @properties = properties
+      end
+
+      def call(path_a, path_b)
+        paths = [path_a, path_b]
+        sanctoralia = paths.collect {|source| sanctorale_from_path source }
+        names = paths.collect {|source| File.basename source }
+
+        differences_found = false
+        all_possible_dates.each do |d|
+          a, b = sanctoralia.collect {|sanctorale| sanctorale[d] }
+
+          0.upto([a.size, b.size].max - 1) do |i|
+            ca = a[i]
+            cb = b[i]
+            compared = [ca, cb]
+
+            if compared.index(&:nil?)
+              differences_found = true
+              notnili = compared.index {|c| !c.nil? }
+
+              print date(d)
+              puts " only in #{names[notnili]}:"
+              puts celebration(compared[notnili])
+              puts
+              next
+            end
+
+            differences = @properties.select do |property|
+              ca.public_send(property) != cb.public_send(property)
+            end
+
+            next if differences.empty?
+            differences_found = true
+            print date(d)
+            puts " differs in #{differences.join(', ')}"
+            puts celebration(ca)
+            puts celebration(cb)
+            puts
+          end
+        end
+
+        !differences_found
+      end
+
+      private
+
+      def all_possible_dates
+        # a leap year must be chosen in order to iterate over
+        # all possible days of a Sanctorale
+        Util::Year.new(1990).each_day
+      end
+
+      def date(d)
+        "#{d.month}/#{d.day}"
+      end
+
+      def celebration(c)
+        symbol_chunk = c.symbol && "#{c.symbol} | "
+
+        "#{c.rank.priority} #{c.colour.symbol} | #{symbol_chunk}#{c.title}"
+      end
+    end
+  end
+end

data/lib/calendarium-romanum/cli/date_parser.rb

@@ -0,0 +1,30 @@
+module CalendariumRomanum
+  class CLI
+    # @api private
+    class DateParser
+      def self.parse(date_str)
+        /(?<year>\d{4})([\/-](?<month>\d{1,2})([\/-](?<day>\d{1,2}))?)?/.match(date_str) do |m|
+          date_segments =
+            %i(year month day)
+              .collect {|name| m[name] }
+              .compact
+              .collect(&:to_i)
+
+          build_range(*date_segments)
+        end || raise(ArgumentError.new('Unparseable date'))
+      end
+
+      def self.build_range(*args)
+        case args.size
+        when 1
+          Util::Year.new(*args)
+        when 2
+          Util::Month.new(*args)
+        else
+          date = Date.new(*args)
+          date..date
+        end
+      end
+    end
+  end
+end

data/lib/calendarium-romanum/cli/dumper.rb

@@ -0,0 +1,68 @@
+module CalendariumRomanum
+  class CLI
+    # Produces a condensed text representation of a Calendar, used in regression tests.
+    # Not loaded by default by +require 'calendarium-romanum'+
+    #
+    # @api private
+    class Dumper
+      def initialize(io=STDOUT)
+        @io = io
+      end
+
+      # Dumps +calendar+. If +other_calendars+ are specified, dumps an alternative entry
+      # for any date for which any of +other_calendars+ differs from +calendar+.
+      def call(calendar, *other_calendars)
+        @io.puts "Calendar for liturgical year #{calendar.year}"
+        calendar.each do |day|
+          dump_day(day)
+
+          other_calendars.each do |cal|
+            day2 = cal[day.date]
+            if day2 != day
+              @io.print 'or '
+              dump_day(day2)
+            end
+          end
+        end
+      end
+
+      # Produces the dump used for regression tests for the specified +year+.
+      def regression_tests_dump(year)
+        sanctorale = Data::GENERAL_ROMAN_LATIN.load
+        calendar = Calendar.new(
+          year,
+          sanctorale,
+          vespers: true
+        )
+        calendar_with_transfers = Calendar.new(
+          Temporale.new(year, transfer_to_sunday: Temporale::SUNDAY_TRANSFERABLE_SOLEMNITIES),
+          sanctorale,
+          vespers: true
+        )
+        calendar_with_extensions = Calendar.new(
+          Temporale.new(year, extensions: Temporale::Extensions.all),
+          sanctorale,
+          vespers: true
+        )
+
+        I18n.with_locale(:la) do
+          call(
+            calendar,
+            calendar_with_transfers,
+            calendar_with_extensions,
+          )
+        end
+      end
+
+      private
+
+      def dump_day(day)
+        @io.puts [day.date, day.season.symbol, day.season_week, !day.vespers.nil?].join(' ')
+
+        day.celebrations.each do |c|
+          @io.puts ['-', c.title.inspect, c.rank.priority, c.colour.symbol, c.symbol, (c.date && "#{c.date.month}/#{c.date.day}"), c.cycle].join(' ')
+        end
+      end
+    end
+  end
+end

data/lib/calendarium-romanum/cli/helper.rb

@@ -0,0 +1,23 @@
+module CalendariumRomanum
+  class CLI
+    # Mixin providing helper methods used by multiple CLI-related classes.
+    #
+    # @api private
+    module Helper
+      def sanctorale_from_path(path)
+        loader = SanctoraleLoader.new
+
+        if path == '-'
+          loader.load(STDIN)
+        else
+          loader.load_from_file(path)
+        end
+      end
+
+      def die!(message, code = 1)
+        STDERR.puts message
+        exit code
+      end
+    end
+  end
+end

data/lib/calendarium-romanum/cli/querier.rb

@@ -0,0 +1,73 @@
+module CalendariumRomanum
+  class CLI
+    # "Queries" a Calendar.
+    # Builds liturgical calendar according to the specified options and
+    # prints calendar entries for the specified period.
+    #
+    # @api private
+    class Querier
+      include Helper
+
+      def initialize(locale: :en, calendar: 'universal-en')
+        @locale = locale
+        @calendar = calendar
+      end
+
+      def call(date_str = nil)
+        I18n.locale = @locale
+
+        pcal = PerpetualCalendar.new sanctorale: sanctorale
+
+        today = Date.today
+        date_range = today..today
+
+        if date_str
+          begin
+            date_range = DateParser.parse(date_str)
+          rescue ArgumentError
+            die! 'Invalid date.'
+          end
+        end
+
+        date_range.each do |day|
+          print_single_date(pcal, day)
+        end
+      end
+
+      private
+
+      def print_single_date(calendar, date)
+        day = calendar.day date
+
+        puts date
+        puts "season: #{day.season.name}"
+        puts
+
+        rank_length = day.celebrations.collect {|c| c.rank.short_desc.nil? ? 0 : c.rank.short_desc.size }.max
+        day.celebrations.each do |c|
+          if [Ranks::PRIMARY, Ranks::TRIDUUM].include? c.rank
+            puts c.title
+          elsif !c.rank.short_desc.nil?
+            print c.rank.short_desc.rjust(rank_length)
+            print ' : '
+            puts c.title
+          end
+        end
+      end
+
+      def sanctorale
+        if File.exist?(@calendar)
+          begin
+            sanctorale_from_path(@calendar)
+          rescue CalendariumRomanum::InvalidDataError
+            die! 'Invalid file format.'
+          end
+        elsif data_file = Data[@calendar]
+          data_file.load
+        else
+          die! "Invalid calendar. Either loading a calendar from filesystem did not succeed, \n or a preinstalled calendar was specified which doesn't exist. See subcommand `calendars` for valid options."
+        end
+      end
+    end
+  end
+end

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,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,19 +19,42 @@ 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_PORTUGUESE = SanctoraleFile.new('universal-pt.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_PORTUGUESE,
+        GENERAL_ROMAN_SPANISH,
+        CZECH,
       ] \
       +
         %w(

data/lib/calendarium-romanum/day.rb

@@ -1,9 +1,16 @@
-require 'forwardable'
-
 module CalendariumRomanum
 
-  # information on one particular day of the liturgical year
+  # Information on one particular day of the liturgical year
   class Day
+    # 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
@@ -12,25 +19,50 @@ module CalendariumRomanum
       @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
+    # 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
 
-    # nil or Celebration from which first Vespers are celebrated
-    # instead of Vespers of the day's other Celebrations.
-    # Please note that Calendar by default *doesn't* populate
-    # Vespers, - it's an opt-in feature.
+    # {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)
@@ -44,28 +76,97 @@ module CalendariumRomanum
 
     # 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, symbol = nil)
-      @title = title
-      @rank = rank
-      @colour = colour
-      @symbol = symbol
+    # 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
@@ -74,25 +175,79 @@ module CalendariumRomanum
       end
     end
 
+    # Liturgical colour
+    #
+    # @return [Colour]
     attr_reader :colour
     alias color colour
 
+    # Symbol uniquely identifying the celebration
+    #
+    # @return [Symbol, nil]
+    # @since 0.5.0
     attr_reader :symbol
 
-    def ==(other)
-      self.class == other.class &&
-        title == other.title &&
-        rank == other.rank &&
-        colour == other.colour
+    # 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
 
-    def change(title: nil, rank: nil, colour: nil, color: nil, symbol: nil)
-      self.class.new(
-        title || self.title,
-        rank || self.rank,
-        colour || color || self.colour,
-        symbol || self.symbol
-      )
+    # 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