calendarium-romanum 0.6.0 → 0.7.0

data/lib/calendarium-romanum/sanctorale_factory.rb

@@ -1,15 +1,50 @@
 module CalendariumRomanum
-  # conveniently creates sanctorale from several data files
+  # Utility loading {Sanctorale} from several sources
+  # and building a single {Sanctorale} by layering them
+  # over each other.
   class SanctoraleFactory
     class << self
-      # layers several sanctorale instances.
+      # Takes several {Sanctorale} instances, returns a new one,
+      # resulting by merging them all together
+      # (using {Sanctorale#update})
+      #
+      # @return [Sanctorale]
+      #
+      # @example
+      #   include CalendariumRomanum
+      #
+      #   prague_sanctorale = SanctoraleFactory.create_layered(
+      #     Data['czech-cs'].load, # Czech Republic
+      #     Data['czech-cechy-cs'].load, # Province of Bohemia
+      #     Data['czech-praha-cs'].load, # Archdiocese of Prague
+      #   )
       def create_layered(*instances)
         r = Sanctorale.new
         instances.each {|i| r.update i }
+
+        metadata = instances
+                     .collect(&:metadata)
+                     .select {|i| i.is_a? Hash }
+        r.metadata = metadata.inject((metadata.first || {}).dup) {|merged,i| merged.update i }
+        r.metadata.delete 'extends'
+        r.metadata['components'] = instances.collect(&:metadata)
+
         r
       end
 
-      # loads and layers several sanctorale instances.
+      # Takes several filesystem paths, loads a {Sanctorale}
+      # from each of them (using {SanctoraleLoader})
+      # and then merges them (using {.create_layered})
+      #
+      # @return [Sanctorale]
+      #
+      # @example
+      #   include CalendariumRomanum
+      #
+      #   my_sanctorale = SanctoraleFactory.load_layered_from_files(
+      #     'my_data/general_calendar.txt',
+      #     'my_data/particular_calendar.txt'
+      #   )
       def load_layered_from_files(*paths)
         loader = SanctoraleLoader.new
         instances = paths.collect do |p|
@@ -17,6 +52,42 @@ module CalendariumRomanum
         end
         create_layered(*instances)
       end
+
+      # Takes a single filesystem path. If the file's YAML front
+      # matter references any parent data files using the
+      # 'extends' key, it loads all the parents and assembles
+      # the resulting {Sanctorale}.
+      # If the data file doesn't reference any parents,
+      # result is the same as {SanctoraleLoader#load_from_file}.
+      #
+      # @return [Sanctorale]
+      # @since 0.7.0
+      def load_with_parents(path)
+        loader = SanctoraleLoader.new
+
+        hierarchy = load_parent_hierarchy(path, loader)
+        return hierarchy.first if hierarchy.size == 1
+
+        create_layered *hierarchy
+      end
+
+      private
+
+      def load_parent_hierarchy(path, loader)
+        main = loader.load_from_file path
+        return [main] unless main.metadata.has_key? 'extends'
+
+        to_merge = [main]
+        parents = main.metadata['extends']
+        parents = [parents] unless parents.is_a? Array
+        parents.reverse.each do |parent_path|
+          expanded_path = File.expand_path parent_path, File.dirname(path)
+          subtree = load_parent_hierarchy(expanded_path, loader)
+          to_merge = subtree + to_merge
+        end
+
+        to_merge
+      end
     end
   end
 end

data/lib/calendarium-romanum/sanctorale_loader.rb

@@ -1,47 +1,62 @@
+require 'yaml'
+
 module CalendariumRomanum
 
-  # understands a plaintext calendar format
-  # and knows how to transform it to Celebrations
-  # and fill them in a Sanctorale
-  #
-  # Format of the file:
-  # 1/31 m : S. Ioannis Bosco, presbyteri
+  # Understands a custom plaintext calendar format
+  # and knows how to transform it to {Celebration}s
+  # and fill them in a {Sanctorale}.
   #
-  # <month>/<day> <rank shortcut> : <title>
-  # rank shortcut is optional, default value is optional memorial
+  # For specification of the data format see {file:data/README.md},
+  # for a complete example see the file describing General Roman Calendar:
+  # {file:data/universal-en.txt}
   class SanctoraleLoader
 
+    # @api private
     RANK_CODES = {
-      nil => Ranks::MEMORIAL_OPTIONAL,
+      nil => Ranks::MEMORIAL_OPTIONAL, # default
       'm' => Ranks::MEMORIAL_GENERAL,
       'f' => Ranks::FEAST_GENERAL,
       's' => Ranks::SOLEMNITY_GENERAL
     }.freeze
+
+    # @api private
     COLOUR_CODES = {
-      nil => Colours::WHITE,
+      nil => Colours::WHITE, # default
       'w' => Colours::WHITE,
       'v' => Colours::VIOLET,
       'g' => Colours::GREEN,
       'r' => Colours::RED
     }.freeze
 
-    # dest should be a Sanctorale,
-    # src anything with #each_line
+    # Load from an object which understands +#each_line+
+    #
+    # @param src [String, File, #each_line]
+    #   source of the loaded data
+    # @param dest [Sanctorale, nil]
+    #   objects to populate. If not provided, a new {Sanctorale}
+    #   instance will be created
+    # @return [Sanctorale]
+    # @raise [InvalidDataError]
     def load(src, dest = nil)
       dest ||= Sanctorale.new
 
       in_front_matter = false
+      front_matter = ''
       month_section = nil
       src.each_line.with_index(1) do |l, line_num|
         # skip YAML front matter
         if line_num == 1 && l.start_with?('---')
           in_front_matter = true
+          front_matter += l
           next
         elsif in_front_matter
           if l.start_with?('---')
             in_front_matter = false
+            dest.metadata = YAML.load(front_matter).freeze
           end
 
+          front_matter += l
+
           next
         end
 
@@ -78,26 +93,52 @@ module CalendariumRomanum
 
     alias load_from_string load
 
+    # Load from a filesystem path
+    #
+    # @param filename [String]
+    # @param dest [Sanctorale, nil]
+    # @param encoding [String]
+    # @return (see #load)
+    # @raise (see #load)
     def load_from_file(filename, dest = nil, encoding = 'utf-8')
       load File.open(filename, 'r', encoding: encoding), dest
     end
 
     private
 
+    def line_regexp
+      @line_regexp ||=
+        begin
+          rank_letters = RANK_CODES.keys.compact.join('')
+          colour_letters = COLOUR_CODES.keys.compact.join('')
+
+          Regexp.new(
+            '^((?<month>\d+)\/)?(?<day>\d+)' + # date
+            '(\s+(?<rank_char>[' + rank_letters + '])?(?<rank_num>\d\.\d{1,2})?)?' + # rank (optional)
+            '(\s+(?<colour>[' + colour_letters + ']))?' + # colour (optional)
+            '(\s+(?<symbol>[\w]{2,}))?' + # symbol (optional)
+            '\s*:(?<title>.*)$', # title
+            Regexp::IGNORECASE
+          )
+        end
+    end
+
     # parses a line containing celebration record,
     # returns a single Celebration
     def load_line(line, month_section = nil)
       # celebration record
-      rank_letters = RANK_CODES.keys.compact.join('')
-      m = line.match(/^((\d+)\/)?(\d+)\s*(([#{rank_letters}])?(\d\.\d{1,2})?)?\s*([WVRG])?\s*(:[\w\d_]+)?\s*:(.*)$/i)
+      m = line.match(line_regexp)
       if m.nil?
         raise RuntimeError.new("Syntax error, line skipped '#{line}'")
       end
 
-      month, day, rank_char, rank_num, colour, symbol_str, title = m.values_at(2, 3, 5, 6, 7, 8, 9)
-      month ||= month_section
-      day = day.to_i
-      month = month.to_i
+      month = (m[:month] || month_section).to_i
+      day = m[:day].to_i
+      rank_char = m[:rank_char]
+      rank_num = m[:rank_num]
+      colour = m[:colour]
+      symbol_str = m[:symbol]
+      title = m[:title]
 
       rank = RANK_CODES[rank_char && rank_char.downcase]
 
@@ -116,7 +157,7 @@ module CalendariumRomanum
 
       symbol = nil
       if symbol_str
-        symbol = symbol_str[1 .. -1].to_sym
+        symbol = symbol_str.to_sym
       end
 
       Celebration.new(

data/lib/calendarium-romanum/temporale.rb

@@ -2,15 +2,26 @@ require 'date'
 
 module CalendariumRomanum
 
-  # determine seasons and dates of Temporale feasts of the given year
+  # One of the two main {Calendar} components.
+  # Handles seasons and celebrations of the temporale cycle
+  # for a given liturgical year.
   class Temporale
 
+    # How many days in a week
     WEEK = 7
 
+    # Which solemnities can be transferred to Sunday
     SUNDAY_TRANSFERABLE_SOLEMNITIES =
       %i(epiphany ascension corpus_christi).freeze
 
-    # year is Integer - the civil year when the liturgical year begins
+    # @param year [Fixnum]
+    #   the civil year when the liturgical year _begins_
+    # @param extensions [Array<#each_celebration>]
+    #   extensions implementing custom temporale celebrations
+    # @param transfer_to_sunday [Array<Symbol>]
+    #   which solemnities should be transferred to a nearby
+    #   Sunday - see {SUNDAY_TRANSFERABLE_SOLEMNITIES}
+    #   for possible values
     def initialize(year, extensions: [], transfer_to_sunday: [])
       @year = year
 
@@ -21,10 +32,14 @@ module CalendariumRomanum
       prepare_solemnities
     end
 
+    # @return [Fixnum]
     attr_reader :year
 
     class << self
       # Determines liturgical year for the given date
+      #
+      # @param date [Date]
+      # @return [Fixnum]
       def liturgical_year(date)
         year = date.year
         temporale = Temporale.new year
@@ -36,14 +51,19 @@ module CalendariumRomanum
         year
       end
 
-      # creates a Calendar for the liturgical year including given
+      # Creates an instance for the liturgical year including given
       # date
+      #
+      # @param date [Date]
+      # @return [Temporale]
       def for_day(date)
         new(liturgical_year(date))
       end
 
-      # factory method creating temporale celebrations
+      # Factory method creating temporale {Celebration}s
       # with sensible defaults
+      #
+      # See {Celebration#initialize} for argument description.
       def create_celebration(title, rank, colour, symbol: nil, date: nil)
         Celebration.new(title, rank, colour, symbol, date, :temporale)
       end
@@ -51,7 +71,7 @@ module CalendariumRomanum
       C = Struct.new(:date_method, :celebration)
       private_constant :C
 
-      # implementation detail, not to be touched by client code
+      # @api private
       def celebrations
         @celebrations ||=
           begin
@@ -90,22 +110,41 @@ module CalendariumRomanum
       end
     end
 
+    # Does this instance transfer the specified solemnity to Sunday?
+    #
+    # @param solemnity [Symbol]
+    # @return [Boolean]
     def transferred_to_sunday?(solemnity)
       @transfer_to_sunday.include?(solemnity)
     end
 
+    # First day of the liturgical year
+    #
+    # @return [Date]
     def start_date
       first_advent_sunday
     end
 
+    # Last day of the liturgical year
+    #
+    # @return [Date]
     def end_date
       Dates.first_advent_sunday(year + 1) - 1
     end
 
+    # Date range of the liturgical year
+    #
+    # @return [Range<Date>]
     def date_range
       start_date .. end_date
     end
 
+    # Check that the date belongs to the liturgical year.
+    # If it does not, throw exception.
+    #
+    # @param date [Date]
+    # @return [void]
+    # @raise [RangeError]
     def range_check(date)
       # necessary in order to handle Date correctly
       date = date.to_date if date.class != Date
@@ -115,6 +154,44 @@ module CalendariumRomanum
       end
     end
 
+    # @!method nativity
+    #   @return [Date]
+    # @!method holy_family
+    #   @return [Date]
+    # @!method mother_of_god
+    #   @return [Date]
+    # @!method epiphany
+    #   @return [Date]
+    # @!method baptism_of_lord
+    #   @return [Date]
+    # @!method ash_wednesday
+    #   @return [Date]
+    # @!method good_friday
+    #   @return [Date]
+    # @!method holy_saturday
+    #   @return [Date]
+    # @!method palm_sunday
+    #   @return [Date]
+    # @!method easter_sunday
+    #   @return [Date]
+    # @!method ascension
+    #   @return [Date]
+    # @!method pentecost
+    #   @return [Date]
+    # @!method holy_trinity
+    #   @return [Date]
+    # @!method corpus_christi
+    #   @return [Date]
+    # @!method mother_of_church
+    #   @return [Date]
+    # @!method sacred_heart
+    #   @return [Date]
+    # @!method christ_king
+    #   @return [Date]
+    # @!method immaculate_heart
+    #   @return [Date]
+    # @!method first_advent_sunday
+    #   @return [Date]
     (celebrations.collect(&:date_method) + [:first_advent_sunday])
       .each do |feast|
       if SUNDAY_TRANSFERABLE_SOLEMNITIES.include? feast
@@ -132,7 +209,12 @@ module CalendariumRomanum
       end
     end
 
-    # which liturgical season is it?
+    # Determine liturgical season for a given date
+    #
+    # @param date [Date]
+    # @return [Season]
+    # @raise [RangeError]
+    #   if the given date doesn't belong to the liturgical year
     def season(date)
       range_check date
 
@@ -157,6 +239,10 @@ module CalendariumRomanum
       end
     end
 
+    # When the specified liturgical season begins
+    #
+    # @param s [Season]
+    # @return [Date]
     def season_beginning(s)
       case s
       when Seasons::ADVENT
@@ -174,6 +260,10 @@ module CalendariumRomanum
       end
     end
 
+    # Determine week of a season for a given date
+    #
+    # @param seasonn [Season]
+    # @param date [Date]
     def season_week(seasonn, date)
       week1_beginning = season_beginning = season_beginning(seasonn)
       unless season_beginning.sunday?
@@ -197,14 +287,23 @@ module CalendariumRomanum
       week
     end
 
+    # Retrieve temporale celebration for the given day
+    #
+    # @param date [Date]
+    # @return [Celebration]
+    # @since 0.6.0
     def [](date)
       @solemnities[date] || @feasts[date] || sunday(date) || @memorials[date] || ferial(date)
     end
 
-    # returns a Celebration
-    # scheduled for the given day
+    # Retrieve temporale celebration for the given day
     #
-    # expected arguments: Date or two Integers (month, day)
+    # @overload get(date)
+    #   @param date [Date]
+    # @overload get(month, day)
+    #   @param month [Fixnum]
+    #   @param day [Fixnum]
+    # @return (see #[])
     def get(*args)
       if args.size == 1 && args[0].is_a?(Date)
         date = args[0]
@@ -219,6 +318,8 @@ module CalendariumRomanum
       self[date]
     end
 
+    # @return [Boolean]
+    # @since 0.6.0
     def ==(b)
       self.class == b.class &&
         year == b.year &&