calendarium-romanum 0.3.0 → 0.7.1

data/lib/calendarium-romanum/sanctorale.rb

@@ -1,27 +1,60 @@
+require 'set'
+
 module CalendariumRomanum
 
-  # knows the fixed-date celebrations
+  # One of the two main {Calendar} components.
+  # Contains celebrations with fixed date, mostly feasts of saints.
+  #
+  # Basically a mapping {AbstractDate} => Array<{Celebration}>
+  # additionally enforcing some constraints:
+  #
+  # - for a given {AbstractDate} there may be multiple {Celebration}s,
+  #   but only if all of them are in the rank of an optional
+  #   memorial
+  # - {Celebration#symbol} must be unique in the whole set of
+  #   contained celebrations
   class Sanctorale
 
     def initialize
       @days = {}
-
       @solemnities = {}
+      @symbols = Set.new
+      @metadata = nil
     end
 
+    # Content subset - only {Celebration}s in the rank(s) of solemnity.
+    #
+    # @return [Hash<AbstractDate=>Celebration>]
     attr_reader :solemnities
 
+    # Sanctorale metadata.
+    #
+    # Data files may contain YAML front matter.
+    # If provided, it's loaded by {SanctoraleLoader} and
+    # stored in this property.
+    # All data files bundled in the gem (see {Data}) have YAML
+    # front matter which is a Hash with a few standardized keys.
+    # While YAML also supports top-level content of other types,
+    # sanctorale data authors should stick to the convention
+    # of using Hash as the top-level data structure of their
+    # front matters.
+    #
+    # @return [Hash, nil]
+    # @since 0.7.0
+    attr_accessor :metadata
+
+    # Adds a new {Celebration}
+    #
+    # @param month [Fixnum]
+    # @param day [Fixnum]
+    # @param celebration [Celebration]
+    # @return [void]
+    # @raise [ArgumentError]
+    #   when performing the operation would break the object's invariant
     def add(month, day, celebration)
       date = AbstractDate.new(month, day)
-      unless @days.has_key? date
-        @days[date] = []
-      end
-
-      if celebration.solemnity?
-        @solemnities[date] = celebration
-      end
 
-      unless @days[date].empty?
+      unless @days[date].nil? || @days[date].empty?
         present = @days[date][0]
         if present.rank != Ranks::MEMORIAL_OPTIONAL
           raise ArgumentError.new("On #{date} there is already a #{present.rank}. No more celebrations can be added.")
@@ -30,33 +63,96 @@ module CalendariumRomanum
         end
       end
 
+      unless celebration.symbol.nil?
+        if @symbols.include? celebration.symbol
+          raise ArgumentError.new("Attempted to add Celebration with duplicate symbol #{celebration.symbol.inspect}")
+        end
+
+        @symbols << celebration.symbol
+      end
+
+      unless @days.has_key? date
+        @days[date] = []
+      end
+
+      if celebration.solemnity?
+        @solemnities[date] = celebration
+      end
+
       @days[date] << celebration
     end
 
-    # replaces content of the given day by given celebrations
-    def replace(month, day, celebrations)
+    # Replaces content of the given day by given {Celebration}s
+    #
+    # @param month [Fixnum]
+    # @param day [Fixnum]
+    # @param celebrations [Array<Celebration>]
+    # @param symbol_uniqueness [true|false]
+    #   allows disabling symbol uniqueness check.
+    #   Internal feature, not intended for use by client code.
+    # @return [void]
+    # @raise [ArgumentError]
+    #   when performing the operation would break the object's invariant
+    def replace(month, day, celebrations, symbol_uniqueness: true)
       date = AbstractDate.new(month, day)
 
+      symbols_without_day = @symbols
+      unless @days[date].nil?
+        old_symbols = @days[date].collect(&:symbol).compact
+        symbols_without_day = @symbols - old_symbols
+      end
+
+      new_symbols = celebrations.collect(&:symbol).compact
+      duplicate = symbols_without_day.intersection new_symbols
+      if symbol_uniqueness && !duplicate.empty?
+        raise ArgumentError.new("Attempted to add Celebrations with duplicate symbols #{duplicate.to_a.inspect}")
+      end
+
+      @symbols = symbols_without_day
+      @symbols.merge new_symbols
+
       if celebrations.first.solemnity?
         @solemnities[date] = celebrations.first
       elsif @solemnities.has_key? date
         @solemnities.delete date
       end
 
-      @days[date] = celebrations
+      @days[date] = celebrations.dup
     end
 
-    # adds all Celebrations from another instance
-    def update(sanctorale)
-      sanctorale.each_day do |date, celebrations|
-        replace date.month, date.day, celebrations
+    # Updates the receiver with {Celebration}s from another instance.
+    #
+    # For each date contained in +other+ the content of +self+
+    # is _replaced_ by that of +other+.
+    #
+    # @param other [Sanctorale]
+    # @return [void]
+    # @raise (see #replace)
+    def update(other)
+      other.each_day do |date, celebrations|
+        replace date.month, date.day, celebrations, symbol_uniqueness: false
       end
+      rebuild_symbols
+    end
+
+    # Retrieves {Celebration}s for the given date
+    #
+    # @param date [AbstractDate, Date]
+    # @return [Array<Celebration>] (may be empty)
+    # @since 0.6.0
+    def [](date)
+      adate = date.is_a?(AbstractDate) ? date : AbstractDate.from_date(date)
+      @days[adate] || []
     end
 
-    # returns an Array with one or more Celebrations
-    # scheduled for the given day
+    # Retrieves {Celebration}s for the given date
     #
-    # expected arguments: Date or two Integers (month, day)
+    # @overload get(date)
+    #   @param date[AbstractDate, 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)
         month = args[0].month
@@ -66,24 +162,74 @@ module CalendariumRomanum
       end
 
       date = AbstractDate.new(month, day)
-      return @days[date] || []
+      self[date]
     end
 
-    # for each day for which an entry is available
-    # yields an AbstractDate and an Array of Celebrations
+    # Enumerates dates for which any {Celebration}s are available
+    #
+    # @yield [AbstractDate, Array<Celebration>] the array is never empty
+    # @return [void, Enumerator] if called without a block, returns +Enumerator+
     def each_day
+      return to_enum(__method__) unless block_given?
+
       @days.each_pair do |date, celebrations|
         yield date, celebrations
       end
     end
 
-    # returns count of the _days_ with celebrations filled
+    # Returns count of _days_ with {Celebration}s filled
+    #
+    # @return [Fixnum]
     def size
       @days.size
     end
 
+    # It is empty if it doesn't contain any {Celebration}
+    #
+    # @return [Boolean]
     def empty?
       @days.empty?
     end
+
+    # Freezes the instance
+    def freeze
+      @days.freeze
+      @days.values.each(&:freeze)
+      @solemnities.freeze
+      super
+    end
+
+    # @return [Boolean]
+    # @since 0.6.0
+    def ==(b)
+      self.class == b.class &&
+        days == b.days
+    end
+
+    protected
+
+    attr_reader :days
+
+    # Builds the registry of celebration symbols anew,
+    # raises error if any duplicates are found.
+    def rebuild_symbols
+      @symbols = Set.new
+      duplicates = []
+
+      @days.each_pair do |date,celebrations|
+        celebrations.each do |celebration|
+          if @symbols.include?(celebration.symbol) &&
+             !duplicates.include?(celebration.symbol)
+            duplicates << celebration.symbol
+          end
+
+          @symbols << celebration.symbol
+        end
+      end
+
+      unless duplicates.empty?
+        raise ArgumentError.new("Duplicate celebration symbols: #{duplicates.inspect}")
+      end
+    end
   end
 end

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,
+      # created 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.is_a?(Hash) && 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

@@ -0,0 +1,176 @@
+require 'yaml'
+
+module CalendariumRomanum
+
+  # Understands a custom plaintext calendar format
+  # and knows how to transform it to {Celebration}s
+  # and fill them in a {Sanctorale}.
+  #
+  # For specification of the data format see {file:data/README.md}
+  # of the data directory, For a complete example see e.g.
+  # {file:universal-en.txt the file describing General Roman Calendar}.
+  class SanctoraleLoader
+
+    # @api private
+    RANK_CODES = {
+      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, # default
+      'w' => Colours::WHITE,
+      'v' => Colours::VIOLET,
+      'g' => Colours::GREEN,
+      'r' => Colours::RED
+    }.freeze
+
+    # 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
+
+        # strip whitespace and comments
+        l.sub!(/#.*/, '')
+        l.strip!
+        next if l.empty?
+
+        # month section heading
+        n = l.match(/^=\s*(\d+)\s*$/)
+        unless n.nil?
+          month_section = n[1].to_i
+          unless month_section >= 1 && month_section <= 12
+            raise error("Invalid month #{month_section}", line_num)
+          end
+          next
+        end
+
+        begin
+          celebration = load_line l, month_section
+        rescue RangeError, RuntimeError => err
+          raise error(err.message, line_num)
+        end
+
+        dest.add(
+          celebration.date.month,
+          celebration.date.day,
+          celebration
+        )
+      end
+
+      dest
+    end
+
+    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
+      m = line.match(line_regexp)
+      if m.nil?
+        raise RuntimeError.new("Syntax error, line skipped '#{line}'")
+      end
+
+      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]
+
+      if rank_num
+        rank_num = rank_num.to_f
+        rank_by_num = Ranks[rank_num]
+
+        if rank_by_num.nil?
+          raise RuntimeError.new("Invalid celebration rank code #{rank_num}")
+        elsif rank_char && (rank.priority.to_i != rank_by_num.priority.to_i)
+          raise RuntimeError.new("Invalid combination of rank letter #{rank_char.inspect} and number #{rank_num}.")
+        end
+
+        rank = rank_by_num
+      end
+
+      symbol = nil
+      if symbol_str
+        symbol = symbol_str.to_sym
+      end
+
+      Celebration.new(
+        title.strip,
+        rank,
+        COLOUR_CODES[colour && colour.downcase],
+        symbol,
+        AbstractDate.new(month, day)
+      )
+    end
+
+    def error(message, line_number)
+      InvalidDataError.new("L#{line_number}: #{message}")
+    end
+  end
+end