calendarium-romanum 0.4.0 → 0.8.0

data/doc/data_readme.md

@@ -0,0 +1,2 @@
+# @title data/README.md
+{include:file:data/README.md}

data/doc/images/class_diagram.puml

@@ -0,0 +1,44 @@
+@startuml
+object Calendar {
+    year
+}
+object PerpetualCalendar
+
+object Temporale
+object Sanctorale
+
+object Day {
+    date
+    season
+    season_week
+    celebrations
+    vespers
+}
+object Celebration {
+    title
+    colour
+    rank
+    date
+    cycle
+    symbol
+}
+object AbstractDate
+object Season
+object Rank
+object Colour
+
+Calendar o-- Temporale
+Calendar o-- Sanctorale
+
+PerpetualCalendar *-- Calendar
+
+Calendar ..> Day : produces
+Temporale ..> Celebration : produces
+Sanctorale "1" --> "0..*" Celebration
+
+Day "1" --> "1..*" Celebration
+Celebration --> Season
+Celebration --> Rank
+Celebration --> Colour
+Celebration --> AbstractDate
+@enduml

data/doc/yard_readme.rdoc

@@ -0,0 +1,76 @@
+= calendarium-romanum
+
+Ruby gem for
+calendar computations according to the Roman Catholic liturgical
+calendar as instituted by
+MP <em>{Mysterii Paschalis}[http://w2.vatican.va/content/paul-vi/en/motu_proprio/documents/hf_p-vi_motu-proprio_19690214_mysterii-paschalis.html]</em> of Paul VI. (AAS 61 (1969), pp. 222-226).
+The rules are defined in
+<em>{General Norms for the Liturgical Year and the Calendar}[https://www.ewtn.com/catholicism/library/liturgical-year-2193]</em>.
+
+== Quickstart
+
+For usage instructions with copy-pastable code examples see {file:README.md}
+
+== Object model overview
+
+rdoc-image:images/class_diagram.png
+
+<b>{CalendariumRomanum::Calendar Calendar}</b> is the library's main functional unit.
+It represents calendar for a single liturgical year and allows retrieving calendar data
+for any of the year's days.
+Calendar basically consists of
+a {CalendariumRomanum::Temporale Temporale} and a {CalendariumRomanum::Sanctorale Sanctorale}
+and it's main task is to combine information from both and for any day of the year produce
+a fully and correctly populated {CalendariumRomanum::Day Day} instance,
+containing one or more {CalendariumRomanum::Celebration Celebrations}
+(see {CalendariumRomanum::Calendar#[] Calendar#[]}).
+
+(+Calendar+ does not own either +Temporale+ or +Sanctorale+ - it is possible to pass them
+on initialization and they are treated as read-only. The only exception is method
+{CalendariumRomanum::Calendar#freeze #freeze}, which freezes all the +Calendar+'s contents,
+including +Temporale+ and +Sanctorale+.)
+
+<b>{CalendariumRomanum::PerpetualCalendar PerpetualCalendar}</b> is a higher-level API
+for retrieving calendar data
+without bothering about liturgical years. It builds {CalendariumRomanum::Calendar Calendar}
+instances internally and passes method calls to them.
+
+<b>{CalendariumRomanum::Day Day}</b> contains complete calendar data of a liturgical day.
+It owns one or more {CalendariumRomanum::Celebration Celebrations}.
+If there are multiple it means that any one of them can be chosen and celebrated
+that day.
+
+<b>{CalendariumRomanum::Celebration Celebration}</b> represents a celebration
+(particular solemnity / feast / memorial / Sunday / ferial)
+and holds it's liturgical properties, encoded mostly by value objects.
+
+(Unlike +Day+, +Celebration+ instances are not bound to a particular date,
+they represent "celebration C in general", not "celebration C in year Y".
+The latter is represented only by a combination of +Celebration+ and +Day+.
++Celebration+ instances are immutable and some may be used repeatedly in context of various
+days and calendars.)
+
+<b>{CalendariumRomanum::Season Season}</b>,
+<b>{CalendariumRomanum::Rank Rank}</b>,
+<b>{CalendariumRomanum::Colour Colour}</b>
+are value objects representing values
+of {CalendariumRomanum::Celebration Celebration} properties.
+Immutable instances representing the standard values are referenced by constants and
+normally there should be no need to create any more.
+
+<b>{CalendariumRomanum::Temporale Temporale}</b> represents the temporale cycle of a single liturgical
+year, computes movable feasts, determines liturgical seasons.
+For any day of the year it provides a temporale {CalendariumRomanum::Celebration Celebration}.
+
+<b>{CalendariumRomanum::Sanctorale Sanctorale}</b> represents the sanctorale cycle, i.e. the fixed-date
+celebrations, mostly feasts of saints. It is not bound to a particular year, hence a single
+instance can be used by many {CalendariumRomanum::Calendar Calendar} instances representing
+various liturgical years. For any day it provides zero or more
+{CalendariumRomanum::Celebration Celebrations}.
+
+Most particular calendars (calendars of countries, provinces, dioceses, churches, religious
+institutes) share the same temporale definition and differ in sanctorale contents.
+Therefore the task of implementing a particular calendar usually consists of populating
+a {CalendariumRomanum::Sanctorale Sanctorale} instance with the desired data.
+A convenient way to do so is preparing a {file:data/README.md sanctorale data file}
+and loading it using {CalendariumRomanum::SanctoraleLoader SanctoraleLoader}.

data/lib/calendarium-romanum.rb

@@ -1,23 +1,36 @@
-%w{
-version
-i18n_setup
-rank
-enum
-enums
-data
-calendar
-perpetual_calendar
-temporale
-temporale/dates
-temporale/extensions/christ_eternal_priest
-sanctorale
-sanctoraleloader
-sanctorale_factory
-transfers
-day
-abstract_date
-util
-ordinalizer
-}.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_predicates
+  rank
+  enum
+  enums
+  errors
+  data
+  day
+  calendar
+  perpetual_calendar
+  temporale/dates
+  temporale/celebration_factory
+  temporale/easter_table
+  temporale/extensions
+  temporale/extensions/christ_eternal_priest
+  temporale/extensions/dedication_before_all_saints
+  temporale
+  sanctorale
+  sanctorale_loader
+  sanctorale_writer
+  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 [Integer]
+    # @param day [Integer]
+    # @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,10 +40,17 @@ module CalendariumRomanum
       month == other.month && day == other.day
     end
 
+    # Produce a +Date+ by providing a year to an +AbstractDate+
+    #
+    # @param year [Integer]
+    # @return [Date]
     def concretize(year)
       Date.new(year, month, day)
     end
 
+    # @since 0.8.0
+    alias in_year concretize
+
     private
 
     def validate!(month, day)

data/lib/calendarium-romanum/calendar.rb

@@ -5,47 +5,76 @@ 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)
+    #
+    # @overload initialize(year, sanctorale = nil, temporale = nil, vespers: false)
+    #   @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}
+    #
+    # @overload initialize(temporale, sanctorale=nil, vespers: false)
+    #   @param temporale [Temporale]
+    #   @param sanctorale [Sanctorale, nil]
+    #     If not provided, the +Calendar+ will only know celebrations
+    #     of the temporale cycle, no feasts of the saints!
+    #   @param vespers [Boolean] Set to true if you want the +Calendar+ to populate {Day#vespers}
+    #   @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)
+      unless year.is_a? Integer
+        temporale = year
+        year = temporale.year
+      end
+
       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.")
+        raise ArgumentError.new('Temporale year must be the same as year.')
       end
 
       @year = year
       @sanctorale = sanctorale || Sanctorale.new
       @temporale = temporale || Temporale.new(year)
-      @transferred = Transfers.new(@temporale, @sanctorale)
+      @populate_vespers = vespers
+
+      @transferred = 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 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
@@ -53,38 +82,103 @@ 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)
-        return new(Temporale.liturgical_year(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
 
-      return year == obj.year
+    # Do {Day} instances returned by this +Calendar+
+    # have {Day#vespers} populated?
+    # @return [Boolean]
+    # @since 0.6.0
+    def populates_vespers?
+      @populate_vespers
     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)
+    # 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) }
+      else
+        day(args)
+      end
+    end
+
+    # 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)
         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
 
@@ -92,25 +186,63 @@ module CalendariumRomanum
         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
@@ -120,11 +252,18 @@ 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 = st.dup << Temporale::CelebrationFactory.saturday_memorial_bvm
+      end
 
       unless st.empty?
         if st.first.rank > t.rank
@@ -134,15 +273,41 @@ module CalendariumRomanum
             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 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
+
+      [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
 
-      return [t]
+      nil
     end
 
     def system_not_effective