calendarium-romanum 0.6.0 → 0.7.0

data/lib/calendarium-romanum.rb

@@ -1,3 +1,9 @@
+# Module wrapping the gem's classes
+#
+# If you hate typing the long module name, see {CR}
+module CalendariumRomanum
+end
+
 %w(
   version
   i18n_setup

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,15 +5,30 @@ 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.
+    #
+    # @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
@@ -32,6 +47,7 @@ module CalendariumRomanum
     end
 
     class << self
+      # @api private
       def mk_date(*args)
         ex = TypeError.new('Date, DateTime or three Integers expected')
 
@@ -51,23 +67,46 @@ 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 [Fixnum]
     attr_reader :year
+
+    # @return [Temporale]
     attr_reader :temporale
+
+    # @return [Sanctorale]
     attr_reader :sanctorale
 
+    # Do {Day} instances returned by this +Calendar+
+    # have {Day#vespers} populated?
+    # @return [Boolean]
+    # @since 0.6.0
     def populates_vespers?
       @populate_vespers
     end
 
-    # Calendars are equal if they have equal settings
+    # 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 &&
@@ -77,18 +116,39 @@ module CalendariumRomanum
         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)
       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 [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)
@@ -126,21 +186,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
-      (temporale.start_date..temporale.end_date)
-        .each { |date| yield(day(date)) }
+      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

data/lib/calendarium-romanum/cli.rb

@@ -2,6 +2,10 @@ 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
 
@@ -131,10 +135,13 @@ module CalendariumRomanum
 
       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
+        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
 

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,19 +18,38 @@ 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_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_ENGLISH,
+        GENERAL_ROMAN_FRENCH,
+        GENERAL_ROMAN_ITALIAN,
+        GENERAL_ROMAN_SPANISH,
+        CZECH,
       ] \
       +
         %w(

data/lib/calendarium-romanum/day.rb

@@ -2,8 +2,17 @@ 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 [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
@@ -12,25 +21,50 @@ module CalendariumRomanum
       @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
+    # 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
 
-    # 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,18 +78,51 @@ 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 one,
   # some have more among which one is to be chosen
   class Celebration
     extend Forwardable
 
+    # @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
@@ -65,11 +132,26 @@ module CalendariumRomanum
       @cycle = cycle
     end
 
-    # Rank instance
+    # @return [Rank]
     attr_reader :rank
 
+    # @!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
@@ -78,20 +160,34 @@ module CalendariumRomanum
       end
     end
 
-    # Colour instance (always set) - liturgical colour
+    # Liturgical colour
+    #
+    # @return [Colour]
     attr_reader :colour
     alias color colour
 
-    # Symbol uniquely identifying the celebration (may be nil)
+    # Symbol uniquely identifying the celebration
+    #
+    # @return [Symbol, nil]
+    # @since 0.5.0
     attr_reader :symbol
 
-    # AbstractDate instance - usual date of the celebration.
+    # 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
 
-    # Symbol :temporale|:sanctorale
     # Describes the celebration as belonging either to the
     # temporale or sanctorale cycle
+    #
+    # @return [:sanctorale, :temporale]
+    # @since 0.6.0
     attr_reader :cycle
 
     def ==(b)
@@ -104,14 +200,27 @@ module CalendariumRomanum
         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,
@@ -122,5 +231,14 @@ module CalendariumRomanum
         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