calendarium-romanum 0.2.1 → 0.7.0

data/lib/calendarium-romanum.rb

@@ -1,19 +1,31 @@
-%w{
-version
-i18n_setup
-rank
-enum
-enums
-data
-calendar
-temporale
-sanctorale
-sanctoraleloader
-sanctorale_factory
-transfers
-day
-abstract_date
-util
-}.each do |f| 
-  require_relative File.join('calendarium-romanum', f) 
+# Module wrapping the gem's classes
+#
+# If you hate typing the long module name, see {CR}
+module CalendariumRomanum
+end
+
+%w(
+  version
+  i18n_setup
+  abstract_date
+  rank
+  enum
+  enums
+  errors
+  data
+  day
+  calendar
+  perpetual_calendar
+  temporale/dates
+  temporale/celebration_factory
+  temporale/extensions/christ_eternal_priest
+  temporale
+  sanctorale
+  sanctorale_loader
+  sanctorale_factory
+  transfers
+  util
+  ordinalizer
+).each do |f|
+  require_relative File.join('calendarium-romanum', f)
 end

data/lib/calendarium-romanum/abstract_date.rb

@@ -4,12 +4,20 @@ module CalendariumRomanum
   class AbstractDate
     include Comparable
 
+    # @param month [Fixnum]
+    # @param day [Fixnum]
+    # @raise [RangeError] on invalid +month+/+day+ value
     def initialize(month, day)
       validate! month, day
       @month = month
       @day = day
     end
 
+    # Build a new instance from a +Date+ (or an object with
+    # similar public interface).
+    #
+    # @param date [Date]
+    # @return [AbstractDate]
     def self.from_date(date)
       new(date.month, date.day)
     end
@@ -32,6 +40,10 @@ module CalendariumRomanum
       month == other.month && day == other.day
     end
 
+    # Produce a +Date+ by providing a year to an +AbstractDate+
+    #
+    # @param year [Fixnum]
+    # @return [Date]
     def concretize(year)
       Date.new(year, month, day)
     end

data/lib/calendarium-romanum/calendar.rb

@@ -5,37 +5,61 @@ 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
 
-    # year: Integer
-    # returns a calendar for the liturgical year beginning with
+    # Day when the implemented calendar system became effective
+    EFFECTIVE_FROM = Date.new(1970, 1, 1).freeze
+
+    # Returns a calendar for the liturgical year beginning with
     # Advent of the specified civil year.
-    def initialize(year, sanctorale=nil)
+    #
+    # @param year [Fixnum]
+    #   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}
+    # @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)
+      if year < (EFFECTIVE_FROM.year - 1)
+        raise system_not_effective
+      end
+
+      if temporale && temporale.year != year
+        raise ArgumentError.new('Temporale year must be the same as year.')
+      end
+
       @year = year
-      @temporale = Temporale.new(year)
       @sanctorale = sanctorale || Sanctorale.new
+      @temporale = temporale || Temporale.new(year)
+      @populate_vespers = vespers
+
       @transferred = Transfers.new(@temporale, @sanctorale)
     end
 
     class << self
+      # @api private
       def mk_date(*args)
         ex = TypeError.new('Date, DateTime or three Integers expected')
 
-        if args.size == 3 then
+        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
+          return Date.new(*args)
 
-        elsif args.size == 1 then
+        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
@@ -43,91 +67,229 @@ module CalendariumRomanum
         end
       end
 
-      # creates a Calendar for the liturgical year including given
-      # date
-      def for_day(date, sanctorale=nil)
-        return new(Temporale.liturgical_year(date), sanctorale)
+      # 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 [Fixnum]
     attr_reader :year
+
+    # @return [Temporale]
     attr_reader :temporale
+
+    # @return [Sanctorale]
     attr_reader :sanctorale
 
-    # returns a Calendar for the subsequent year
-    def succ
-      c = Calendar.new @year + 1, @sanctorale
-      return c
+    # Do {Day} instances returned by this +Calendar+
+    # have {Day#vespers} populated?
+    # @return [Boolean]
+    # @since 0.6.0
+    def populates_vespers?
+      @populate_vespers
     end
 
-    # returns a Calendar for the previous year
-    def pred
-      c = Calendar.new @year - 1, @sanctorale
-      return c
+    # 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
 
-    def ==(obj)
-      unless obj.is_a? Calendar
-        return false
+    # 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) }
+      else
+        day(args)
       end
-
-      return year == obj.year
     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
-    def day(*args)
+    # 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 [Fixnum]
+    #   @param month [Fixnum]
+    #   @param day [Fixnum]
+    # @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)
         unless @temporale.date_range.include? date
           date = Date.new(@year + 1, *args)
         end
       else
-        date = self.class.mk_date *args
+        date = self.class.mk_date(*args)
         range_check date
       end
 
+      if date < EFFECTIVE_FROM
+        raise system_not_effective
+      end
+
+      celebrations = celebrations_for(date)
+      vespers_celebration = nil
+      if @populate_vespers || vespers
+        begin
+          vespers_celebration = first_vespers_on(date, celebrations)
+        rescue RangeError
+          # there is exactly one possible case when
+          # range_check(date) passes and range_check(date + 1) fails:
+          vespers_celebration = Temporale::CelebrationFactory.first_advent_sunday
+        end
+      end
+
       s = @temporale.season(date)
-      return Day.new(
-                     date: date,
-                     season: s,
-                     season_week: @temporale.season_week(s, date),
-                     celebrations: celebrations_for(date)
-                    )
+      Day.new(
+        date: date,
+        season: s,
+        season_week: @temporale.season_week(s, date),
+        celebrations: celebrations,
+        vespers: vespers_celebration
+      )
+    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
+      super
+    end
+
+    private
+
     def celebrations_for(date)
       tr = @transferred.get(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 = st.dup << Temporale::CelebrationFactory.saturday_memorial_bvm
+      end
 
       unless st.empty?
         if st.first.rank > t.rank
           if st.first.rank == Ranks::MEMORIAL_OPTIONAL
-            st.unshift t
-            return st
+            return st.dup.unshift t
           else
             return st
           end
+        elsif t.rank == Ranks::FERIAL_PRIVILEGED && st.first.rank.memorial?
+          commemorations = st.collect do |c|
+            c.change(rank: Ranks::COMMEMORATION, colour: t.colour)
+          end
+          return commemorations.unshift t
+        elsif t.symbol == :immaculate_heart &&
+              [Ranks::MEMORIAL_GENERAL, Ranks::MEMORIAL_PROPER].include?(st.first.rank)
+          optional_memorials = ([t] + st).collect do |celebration|
+            celebration.change rank: Ranks::MEMORIAL_OPTIONAL
+          end
+          ferial = temporale.send :ferial, date # ugly and evil
+          return [ferial] + optional_memorials
         end
       end
 
-      return [t]
+      [t]
+    end
+
+    def first_vespers_on(date, celebrations)
+      tomorrow = date + 1
+      tomorrow_celebrations = celebrations_for(tomorrow)
+
+      c = tomorrow_celebrations.first
+      if c.rank >= Ranks::SOLEMNITY_PROPER ||
+         c.rank == Ranks::SUNDAY_UNPRIVILEGED ||
+         (c.rank == Ranks::FEAST_LORD_GENERAL && tomorrow.sunday?)
+        if c.symbol == :ash_wednesday || c.symbol == :good_friday
+          return nil
+        end
+
+        if c.rank > celebrations.first.rank || c.symbol == :easter_sunday
+          return c
+        end
+      end
+
+      nil
+    end
+
+    def system_not_effective
+      RangeError.new('Year out of range. Implemented calendar system has been in use only since 1st January 1970.')
     end
   end # class Calendar
 end

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