calendarium-romanum 0.5.0 → 0.9.0

data/lib/calendarium-romanum/calendar.rb

@@ -1,20 +1,52 @@
-require 'date'
 require 'forwardable'
 
 module CalendariumRomanum
 
   # Provides complete information concerning a liturgical year,
   # it's days and celebrations occurring on them.
+  #
+  # {Calendar}'s business logic is mostly about correctly combining
+  # information from {Temporale} and {Sanctorale}.
   class Calendar
     extend Forwardable
 
     # Day when the implemented calendar system became effective
     EFFECTIVE_FROM = Date.new(1970, 1, 1).freeze
 
-    # year: Integer
-    # returns a calendar for the liturgical year beginning with
+    # Returns a calendar for the liturgical year beginning with
     # Advent of the specified civil year.
-    def initialize(year, sanctorale = nil, temporale = nil, vespers: false)
+    #
+    # @overload initialize(year, sanctorale = nil, temporale = nil, vespers: false, transfers: nil)
+    #   @param year [Integer]
+    #     Civil year when the liturgical year begins.
+    #   @param sanctorale [Sanctorale, nil]
+    #     If not provided, the +Calendar+ will only know celebrations
+    #     of the temporale cycle, no feasts of the saints!
+    #   @param temporale [Temporale, nil]
+    #     If not provided, +Temporale+ for the given year with default
+    #     configuration will built.
+    #   @param vespers [Boolean] Set to true if you want the +Calendar+ to populate {Day#vespers}
+    #   @param transfers [#call, nil]
+    #     Object with the same public interface as the +Transfers+ class (really class,
+    #     not instance!), responsible for handling transfers of conflicting solemnities.
+    #     Only useful for overriding the default solemnity transfer logic with a custom one.
+    #
+    # @overload initialize(temporale, sanctorale=nil, vespers: false, transfers: nil)
+    #   @param temporale [Temporale]
+    #   @param sanctorale [Sanctorale, nil]
+    #   @param vespers [Boolean]
+    #   @param transfers [#call, nil]
+    #   @since 0.8.0
+    #
+    # @raise [RangeError]
+    #   if +year+ is specified for which the implemented calendar
+    #   system wasn't in force
+    def initialize(year, sanctorale = nil, temporale = nil, vespers: false, transfers: nil)
+      unless year.is_a? Integer
+        temporale = year
+        year = temporale.year
+      end
+
       if year < (EFFECTIVE_FROM.year - 1)
         raise system_not_effective
       end
@@ -28,26 +60,23 @@ module CalendariumRomanum
       @temporale = temporale || Temporale.new(year)
       @populate_vespers = vespers
 
-      @transferred = Transfers.new(@temporale, @sanctorale)
+      @transferred = (transfers || Transfers).call(@temporale, @sanctorale).freeze
     end
 
     class << self
+      # @api private
       def mk_date(*args)
         ex = TypeError.new('Date, DateTime or three Integers expected')
 
         if args.size == 3
           args.each do |a|
-            unless a.is_a? Integer
-              raise ex
-            end
+            raise ex unless a.is_a? Integer
           end
           return Date.new(*args)
 
         elsif args.size == 1
           a = args.first
-          unless a.is_a? Date
-            raise ex
-          end
+          raise ex unless a.is_a? Date
           return a
 
         else
@@ -55,38 +84,95 @@ module CalendariumRomanum
         end
       end
 
-      # creates a Calendar for the liturgical year including given
-      # date
+      # Creates a new instance for the liturgical year which includes
+      # given date
+      #
+      # @param date [Date]
+      # @param constructor_args
+      #   arguments that will be passed to {initialize}
+      # @return [Calendar]
       def for_day(date, *constructor_args)
         new(Temporale.liturgical_year(date), *constructor_args)
       end
     end # class << self
 
+    # @!method range_check(date)
+    #   @see Temporale#range_check
+    #   @param date
+    #   @return [void]
+    # @!method season(date)
+    #   @see Temporale#season
+    #   @param date
+    #   @return [Season]
     def_delegators :@temporale, :range_check, :season
+
+    # @return [Integer]
     attr_reader :year
+
+    # @return [Temporale]
     attr_reader :temporale
+
+    # @return [Sanctorale]
     attr_reader :sanctorale
 
-    def ==(obj)
-      unless obj.is_a? Calendar
-        return false
-      end
+    # Solemnities transferred to a date different from the usual one
+    # due to occurrence with a higher-ranking celebration.
+    #
+    # @return [Hash<Date=>Celebration>]
+    # @since 0.8.0
+    attr_reader :transferred
+
+    # Do {Day} instances returned by this +Calendar+
+    # have {Day#vespers} populated?
+    # @return [Boolean]
+    # @since 0.6.0
+    def populates_vespers?
+      @populate_vespers
+    end
 
-      year == obj.year
+    # Two +Calendar+s are equal if they have equal settings
+    # (which means that to equal input they return equal data)
+    def ==(b)
+      b.class == self.class &&
+        year == b.year &&
+        populates_vespers? == b.populates_vespers? &&
+        temporale == b.temporale &&
+        sanctorale == b.sanctorale
     end
 
+    # Retrieve liturgical calendar information for the specified day
+    # or range of days.
+    #
+    # @overload [](date)
+    #   @param date [Date]
+    #   @return [Day]
+    # @overload [](range)
+    #   @param range [Range<Date>]
+    #   @return [Array<Day>]
     def [](args)
-      if(args.is_a?(Range))
-        args.map{|date| day(date)}
+      if args.is_a?(Range)
+        args.map {|date| day(date) }
       else
-        day(*args)
+        day(args)
       end
     end
 
-    # accepts date information represented as
-    # Date, DateTime, or two to three integers
-    # (month - day or year - month - day);
-    # returns filled Day for the specified day
+    # Retrieve liturgical calendar information for the specified day
+    #
+    # @overload day(date, vespers: false)
+    #   @param date [Date]
+    # @overload day(year, month, day, vespers: false)
+    #   @param year [Integer]
+    #   @param month [Integer]
+    #   @param day [Integer]
+    # @param vespers [Boolean]
+    #   Set to +true+ in order to get {Day} with {Day#vespers}
+    #   populated (overrides instance-wide setting {#populates_vespers?}).
+    # @return [Day]
+    # @raise [RangeError]
+    #   If a date is specified on which the implemented calendar
+    #   system was not yet in force (it became effective during
+    #   the liturgical year 1969/1970)
     def day(*args, vespers: false)
       if args.size == 2
         date = Date.new(@year, *args)
@@ -124,16 +210,41 @@ module CalendariumRomanum
       )
     end
 
+    # Iterate over the whole liturgical year, day by day,
+    # for each day yield calendar data.
+    # If called without a block, returns +Enumerator+.
+    #
+    # @yield [Day]
+    # @return [void, Enumerator]
+    # @since 0.6.0
+    def each
+      return to_enum(__method__) unless block_given?
+
+      temporale.date_range
+        .each {|date| yield(day(date)) }
+    end
+
     # Sunday lectionary cycle
+    #
+    # @return [Symbol]
+    #   For possible values see {LECTIONARY_CYCLES}
     def lectionary
       LECTIONARY_CYCLES[@year % 3]
     end
 
     # Ferial lectionary cycle
+    #
+    # @return [1, 2]
     def ferial_lectionary
       @year % 2 + 1
     end
 
+    # Freezes the instance.
+    #
+    # *WARNING*: {Temporale} and {Sanctorale} instances passed
+    # to the +Calendar+ on initialization will be frozen, too!
+    # This is necessary, because a +Calendar+ would not really be
+    # frozen were it possible to mutate it's key components.
     def freeze
       @temporale.freeze
       @sanctorale.freeze
@@ -143,25 +254,31 @@ module CalendariumRomanum
     private
 
     def celebrations_for(date)
-      tr = @transferred.get(date)
+      tr = @transferred[date]
       return [tr] if tr
 
-      t = @temporale.get date
-      st = @sanctorale.get date
+      t = @temporale[date]
+      st = @sanctorale[date]
+
+      if date.saturday? &&
+         @temporale.season(date) == Seasons::ORDINARY &&
+         (st.empty? || st.first.rank == Ranks::MEMORIAL_OPTIONAL) &&
+         t.rank <= Ranks::MEMORIAL_OPTIONAL
+        st += [Temporale::CelebrationFactory.saturday_memorial_bvm]
+      end
 
       unless st.empty?
         if st.first.rank > t.rank
           if st.first.rank == Ranks::MEMORIAL_OPTIONAL
-            return st.dup.unshift t
+            return [t] + st
           else
             return st
           end
         elsif t.rank == Ranks::FERIAL_PRIVILEGED && st.first.rank.memorial?
-          st = st.collect do |c|
-            Celebration.new(c.title, Ranks::COMMEMORATION, t.colour)
+          commemorations = st.collect do |c|
+            c.change(rank: Ranks::COMMEMORATION, colour: t.colour)
           end
-          st.unshift t
-          return st
+          return [t] + commemorations
         elsif t.symbol == :immaculate_heart &&
               [Ranks::MEMORIAL_GENERAL, Ranks::MEMORIAL_PROPER].include?(st.first.rank)
           optional_memorials = ([t] + st).collect do |celebration|

data/lib/calendarium-romanum/cli.rb

@@ -1,136 +1,116 @@
 require 'thor'
 
+# monkey patch preventing Thor from screwing formatting in our commands' long_desc
+# credits: https://github.com/erikhuda/thor/issues/398#issuecomment-237400762
+class Thor
+  module Shell
+    class Basic
+      def print_wrapped(message, options = {})
+         stdout.puts message
+       end
+    end
+  end
+end
+
 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
+    desc 'query [DATE]', 'show calendar information for a specified date/month/year'
+    long_desc <<-EOS
+show calendar information for a specified date/month/year
+
+DATE formats:
+not specified - today
+2000-01-02    - single date
+2000-01       - month
+2000          - year
+EOS
+    option :calendar, default: Data::GENERAL_ROMAN_ENGLISH.siglum, aliases: :c, desc: 'sanctorale data file to use (filesystem path or identifier of a bundled one)'
+    option :locale, default: 'en', aliases: :l, desc: 'locale to use for localized strings'
     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]
-
-        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
-        sanctorale = data_file.load
-      end
-
-      pcal = PerpetualCalendar.new sanctorale: sanctorale
-
-      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
+      Querier
+        .new(locale: options[:locale], calendar: options[:calendar])
+        .call(date_str)
     end
 
-    desc 'calendars', 'lists calendars available for querying'
+    desc 'calendars', 'list calendars available for querying'
     def calendars
       Data.each {|c| puts c.siglum }
     end
 
-    desc 'errors FILE1, ...', 'finds errors in sanctorale data files'
+    desc 'errors FILE1 ...', 'find errors in sanctorale data files'
     def errors(*files)
-      loader = SanctoraleLoader.new
       files.each do |path|
-        s = Sanctorale.new
         begin
-          loader.load_from_file path, s
+          sanctorale_from_path path
         rescue Errno::ENOENT, InvalidDataError => err
           die! err.message
         end
       end
     end
 
-    desc 'cmp FILE1, FILE2', 'detect differences in rank and colour of corresponding celebrations'
+    desc 'cmp FILE1 FILE2', 'detect differences between two sanctorale data files'
+    option :no_rank, type: :boolean, desc: 'ignore differences of rank'
+    option :no_colour, type: :boolean, desc: 'ignore differences of colour'
+    option :no_symbol, type: :boolean, desc: 'ignore differences of symbol'
+    option :title, type: :boolean, desc: 'report differences of title'
     def cmp(a, b)
-      loader = SanctoraleLoader.new
-      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|
-        a, b = sanctoralia.collect {|s| s.get(d) }
-
-        0.upto([a.size, b.size].max - 1) do |i|
-          ca = a[i]
-          cb = b[i]
-          compared = [ca, cb]
-          differences = []
-
-          if compared.index(&:nil?)
-            notnili = compared.index {|c| !c.nil? }
-
-            print date(d)
-            puts " only in #{names[notnili]}:"
-            puts celebration(compared[notnili])
-            puts
-            next
-          end
-
-          differences << 'rank' if ca.rank != cb.rank
-          differences << 'colour' if ca.colour != cb.colour
-
-          next if differences.empty?
-          print date(d)
-          puts " differs in #{differences.join(', ')}"
-          puts celebration(ca)
-          puts celebration(cb)
-          puts
+      properties = Comparator::DEFAULT_PROPERTIES
+      options.each_key do |k|
+        if k.start_with? 'no_'
+          properties.delete k.sub('no_', '').to_sym
+        else
+          properties << k.to_sym
         end
       end
+      Comparator.new(properties).call(a, b) || exit(1)
     end
 
-    private
-
-    def date(d)
-      "#{d.month}/#{d.day}"
+    desc 'merge FILE1 ...', 'loads sanctorale data files on top of each other, prints the resulting sanctorale'
+    option :front_matter, type: :boolean, desc: 'output YAML front matter'
+    def merge(*files)
+      sanctoralia = files.collect {|path| sanctorale_from_path path }
+      merged = SanctoraleFactory.create_layered *sanctoralia
+      SanctoraleWriter.new(front_matter: options[:front_matter]).write merged, STDOUT
     end
 
-    def celebration(c)
-      "#{c.rank.priority} #{c.colour.symbol} | #{c.title}"
+    desc 'id FILE', 'print celebration identifiers found in a sanctorale data file'
+    def id(file)
+      sanctorale_from_path(file).each_day do |_, celebrations|
+        celebrations.each do |c|
+          puts c.symbol if c.symbol
+        end
+      end
     end
 
-    def die!(message, code = 1)
-      STDERR.puts message
-      exit code
+    desc 'dump YEAR', 'print calendar of the specified year for use in regression tests'
+    def dump(year)
+      Dumper.new.regression_tests_dump year.to_i
     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|
-        next if c.rank.short_desc.nil?
-        print c.rank.short_desc.rjust(rank_length)
-        print ' : '
-        puts c.title
-      end
+    desc 'version', 'print version information'
+    def version
+      puts 'calendarium-romanum CLI'
+      puts "calendarium-romanum: version #{CalendariumRomanum::VERSION}, released #{CalendariumRomanum::RELEASE_DATE}"
     end
+  end
+end
+
+# required files reopen the CLI class - require after the class'es main definition
+# in order to prevent superclass mismatch errors
+require_relative 'cli/helper'
 
+module CalendariumRomanum
+  class CLI
+    include Helper
   end
 end
+
+require_relative 'cli/comparator'
+require_relative 'cli/date_parser'
+require_relative 'cli/dumper'
+require_relative 'cli/querier'