calendarium-romanum 0.3.0 → 0.7.1

data/lib/calendarium-romanum/cli.rb

@@ -2,45 +2,47 @@ require 'thor'
 
 module CalendariumRomanum
 
+  # Implementation of the +calendariumrom+ executable.
+  # _Not_ loaded by default when you +require+ the gem.
+  #
+  # @api private
   class CLI < Thor
     include CalendariumRomanum::Util
 
     desc 'query 2007-06-05', 'show calendar information for a specified date'
     option :calendar, default: 'universal-en', aliases: :c
     option :locale, default: 'en', aliases: :l
-    def query(date_str=nil)
+    def query(date_str = nil)
       I18n.locale = options[:locale]
+      calendar = options[:calendar]
+      if File.exist?(calendar)
+        begin
+          sanctorale = SanctoraleLoader.new.load_from_file(calendar)
+        rescue CalendariumRomanum::InvalidDataError
+          die! 'Invalid file format.'
+        end
+      else
+        data_file = Data[calendar]
 
-      data_file = Data[options[:calendar]]
-      if data_file.nil?
-        STDERR.puts 'Invalid calendar. See subcommand `calendars` for valid options.'
-        exit 1
-      end
-      sanctorale = data_file.load
-
-      date =
-        if date_str
-          begin
-            Date.parse(date_str)
-          rescue ArgumentError
-            STDERR.puts 'Invalid date.'
-            exit 1
-          end
-        else
-          Date.today
+        if data_file.nil?
+          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
-      calendar = Calendar.for_day(date, sanctorale)
-      day = calendar.day date
+        sanctorale = data_file.load
+      end
 
-      puts date
-      puts "season: #{day.season}"
-      puts
+      pcal = PerpetualCalendar.new sanctorale: sanctorale
 
-      rank_length = day.celebrations.collect {|c| c.rank.short_desc.size }.max
-      day.celebrations.each do |c|
-        print c.rank.short_desc.rjust(rank_length)
-        print ' : '
-        puts c.title
+      if date_str
+        begin
+          parsed_date = DateParser.new(date_str)
+          parsed_date.date_range.each do |day|
+            print_single_date(pcal, day)
+          end
+        rescue ArgumentError
+          die! 'Invalid date.'
+        end
+      else
+        print_single_date(pcal, Date.today)
       end
     end
 
@@ -54,47 +56,94 @@ module CalendariumRomanum
       loader = SanctoraleLoader.new
       files.each do |path|
         s = Sanctorale.new
-        loader.load_from_file path, s
+        begin
+          loader.load_from_file path, s
+        rescue Errno::ENOENT, InvalidDataError => err
+          die! err.message
+        end
       end
     end
 
     desc 'cmp FILE1, FILE2', 'detect differences in rank and colour of corresponding celebrations'
     def cmp(a, b)
       loader = SanctoraleLoader.new
-      sanctorales = []
-
-      [a, b].each do |source|
-        s = Sanctorale.new
-        loader.load_from_file source, s
-        sanctorales << s
-      end
+      paths = [a, b]
+      sanctoralia = paths.collect {|source| loader.load_from_file source }
+      names = paths.collect {|source| File.basename source }
 
       # a leap year must be chosen in order to iterate over
       # all possible days of a Sanctorale
       Year.new(1990).each_day do |d|
-        celebs = sanctorales.collect {|s| s.get d.month, d.day }
-        if celebs.find {|cc| cc.nil? }
-          next
-        end
+        a, b = sanctoralia.collect {|s| s.get(d) }
 
-        celebs[0].each_index do |i|
-          if i >= celebs[1].size
-            break
-          end
-
-          ca = celebs[0][i]
-          cb = celebs[1][i]
+        0.upto([a.size, b.size].max - 1) do |i|
+          ca = a[i]
+          cb = b[i]
+          compared = [ca, cb]
 
-          _print_cel = Proc.new {|c| puts "#{c.rank.priority} #{c.colour} | #{c.title}" }
+          if compared.index(&:nil?)
+            notnili = compared.index {|c| !c.nil? }
 
-          if ca.rank != cb.rank || ca.colour != cb.colour
-            puts "#{d.month}/#{d.day}"
-            _print_cel.call ca
-            _print_cel.call cb
+            print date(d)
+            puts " only in #{names[notnili]}:"
+            puts celebration(compared[notnili])
             puts
+            next
           end
+
+          differences = %i(rank colour symbol).select do |property|
+            ca.public_send(property) != cb.public_send(property)
+          end
+
+          next if differences.empty?
+          print date(d)
+          puts " differs in #{differences.join(', ')}"
+          puts celebration(ca)
+          puts celebration(cb)
+          puts
         end
       end
     end
+
+    desc 'version', 'print version information'
+    def version
+      puts 'calendarium-romanum CLI'
+      puts "calendarium-romanum: version #{CalendariumRomanum::VERSION}, released #{CalendariumRomanum::RELEASE_DATE}"
+    end
+
+    private
+
+    def date(d)
+      "#{d.month}/#{d.day}"
+    end
+
+    def celebration(c)
+      "#{c.rank.priority} #{c.colour.symbol} | #{c.title}"
+    end
+
+    def die!(message, code = 1)
+      STDERR.puts message
+      exit code
+    end
+
+    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
+
   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,16 @@
 module CalendariumRomanum
-  # allows easy access to 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,52 +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} 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
@@ -56,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