ess 0.9.3 → 1.0.0

data/README.md

@@ -3,13 +3,13 @@ ruby-ess [![ESS Feed Standard](http://essfeed.org/images/8/87/ESS_logo_32x32.png
 
 [![Build Status](https://travis-ci.org/essfeed/ruby-ess.png)](https://travis-ci.org/essfeed/ruby-ess)
 
-Generate ESS XML feeds with Ruby
+Generate and parse ESS XML feeds with Ruby
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'ess', '~> 0.9.3'
+    gem 'ess', '~> 1.0.0'
 
 And then execute:
 
@@ -17,12 +17,18 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install ess -v 0.9.3
+    $ gem install ess -v 1.0.0
+
+## Information
+
+* RDoc documentation [available on RubyDoc.info](http://rubydoc.info/gems/ess/frames)
+* Source code [available on GitHub](http://github.com/essfeed/ruby-ess)
 
 ## Usage
 
-Producing your own ESS feeds is easy. Here is an example about how
-it's done, with most of the available tags available in ESS:
+Producing your own ESS feeds is easy. Here is a rather extensive
+example about how it's done, with most of the available tags
+available in ESS:
 
 ```ruby
 
@@ -411,6 +417,73 @@ can be assigned to the ID tag of a channel or feed, and if it doesn't
 start with "ESSID:" or "EVENTID:", it will be regenerated using that
 string as the key.
 
+### Parsing ESS files
+
+There is also an ESS::Parser class, which has one method "#parse"
+which accepts a string containing the ESS/XML document, or a File
+object. It parses the document and returns an ESS::ESS object,
+which represents the root elements of an ESS document.
+
+This object has methods which correspond to child tags, and each
+method retrieves another object which represents a child tag with
+that name, and which again has methods corresponding to its child
+elements. I believe it's all easier to understand from an example:
+
+```ruby
+
+ess = ESS::Parser.parse(xml_doc)
+
+# To retrieve a child tag, just use a method with the same name
+title_tag = ess.channel.title
+
+# To retrieve a tags text, use the #text! method
+title_text = title_tag.text!
+
+# Some tags car be repeated more then once. For that case the tag
+# objects accept tag_name_list methods, which return a list of child
+# tags named "tag_name", like this:
+feeds = ess.channel.feed_list
+feeds.each do |feed|
+  puts feed.title.text!
+end
+
+# For reading attribute values, the objects accept attr_name_attr
+# methods, for example, to retrieve the value of attribute "type" of
+# a "item" tag:
+item = feeds[0].dates.item_list[0]
+date_item_type = item.type_attr
+
+```
+
+#### find_coming and find_between
+
+To aid web developers who want to display events in a list or a
+calendar, the ESS::ESS objects returned by the parser have two
+additional methods: find_coming and find_between.
+
+find_coming tries to find the next N events for your event list.
+It returns a list of hashes, each hash representing one item for
+the list. The hash contains the :time and :feed keys, the former
+being the start time of the event, and the later the complete
+feed describing the whole event.
+
+find_coming accepts two parameters. The first parameter is the
+number of events it should return and the default is 10. The second
+parameter defaults to Time.now, and the method with return N events
+starting from the moment specified.
+
+find_between returns a list of all events between the two moments
+in time, which as specified as parameters with Time objects. For
+example, to retrieve all events in June 2013, run this:
+
+```ruby
+
+start_time = "2013-06-01 00:00"
+end_time = "2013-06-30 24:00"
+events = ess.find_between(start_time, end_time)
+
+```
+
 ## Contributing
 
 1. Fork it

data/lib/ess/dtd.rb

@@ -3,6 +3,10 @@ require 'ess/validation'
 
 module ESS
   module DTD
+    ##
+    # The information in this module should not be used directly, it is
+    # intended for the document builder and parser.
+    #
     include ESS::Postprocessing
     include ESS::Validation
 
@@ -327,7 +331,7 @@ module ESS
                  :country_code => { :dtd => COUNTRY_CODE,
                                     :mandatory => false,
                                     :max_occurs => 1 },
-                 :email => { :dtd => BASIC_ELEMENT,
+                 :email => { :dtd => EMAIL,
                              :mandatory => false,
                              :max_occurs => 1 },
                  :phone => { :dtd => BASIC_ELEMENT,
@@ -480,6 +484,12 @@ module ESS
     }
 
     class InvalidValueError < RuntimeError
+      ##
+      # This exception is generated when the builder or parser
+      # receive a value which is not valid for a tag or attribute.
+      # It should contain a message describing what was the value which
+      # caused it to be raised.
+      #
     end
   end
 end

data/lib/ess/element.rb

@@ -4,27 +4,61 @@ require 'ess/pusher'
 
 module ESS
   class Element
+    ##
+    # Objects of this class represent the various tags available in ESS
+    #
+
+
     include ESS::Helpers
 
-    attr_reader :dtd
+    ##
+    # Returns the dictionary describing this tag.
+    #
+    def dtd
+      return @dtd
+    end
 
+    ##
+    # There should never be a need to create an Element object yourself,
+    # except if you're the developer of this library. Use ESS::Maker.make
+    # if you need to create a new ESS document.
+    # 
+    # === Parameters
+    #
+    # [name] a symbol, the name of the tag being created
+    # [dtd] a hash describing the tag
+    #
     def initialize name, dtd
       @name, @dtd = name, dtd
     end
 
+    ##
+    # Return the name of the tag as a symbol.
+    #
     def name!
       @name
     end
 
+    ##
+    # Returns or sets the text contained in this tag
+    #
     def text! text=nil
       return @text ||= "" if text.nil?
       @text = do_text_postprocessing_of text
     end
 
+    ##
+    # Returns a short description of this object.
+    #
     def inspect
       "#<#{self.class}:#{object_id} text=\"#{@text}\">"
     end
 
+    ##
+    # Validates the tag according to its DTD and all child tags. Throws an
+    # ESS::Validation::ValidationError exception in case the document is
+    # incomplete or an invalid value if found.
+    #
     def validate
       run_tag_validators
       check_attributes
@@ -32,6 +66,10 @@ module ESS
       return nil # if no errors found, i.e. no exceptions have been raised
     end
 
+    ##
+    # Same as #validate, but returns false if an error is found, instead of
+    # throwing exceptions.
+    #
     def valid?
       begin
         validate
@@ -41,6 +79,11 @@ module ESS
       return true
     end
 
+    ##
+    # Returns the feed as an XML document in a string. An Builder::XmlMarkup
+    # object can be passed as an argument and used as output, instead of
+    # generating a string object.
+    #
     def to_xml! xml=nil
       convert_to_string = true if xml.nil?
       xml = Builder::XmlMarkup.new if xml.nil?
@@ -61,16 +104,48 @@ module ESS
       xml.target! if convert_to_string
     end
 
+    ##
+    # A convenience method for pushing the current document to aggregators.
+    # It calls the ESS::Pusher.push_to_aggregators method and passes all
+    # options to it.
+    #
     def push_to_aggregators options={}
       raise RuntimeError, "only ESS root element can be pushed to aggregators" if @name != :ess
       options[:data] = self.to_xml!
       Pusher::push_to_aggregators options
     end
 
+    ##
+    # Same as #to_xml!, but accepts no arguments.
+    #
     def to_s
       to_xml!
     end
 
+    ##
+    # Disables postprocessing of tag values.
+    #
+    def disable_postprocessing
+      @@postprocessing_disabled = true
+    end
+
+    ##
+    # Enables postprocessing of tag values.
+    def enable_postprocessing
+      @@postprocessing_disabled = false
+    end
+
+    ##
+    # Returns true if postprocessing has been disabled.
+    #
+    def postprocessing_disabled?
+      @@postprocessing_disabled ||= false
+    end
+
+    ##
+    # Handles methods corresponding to a tag name, ending with either
+    # _list or _attr, or starting with add_ .
+    #
     def method_missing m, *args, &block
       if method_name_is_tag_name? m
         return assign_tag(m, args, &block)
@@ -156,8 +231,10 @@ module ESS
       end
 
       def run_post_processing tag
-        if @dtd[:tags][tag.name!].keys.include? :postprocessing
-          @dtd[:tags][tag.name!][:postprocessing].each { |processor| processor.process(self, tag) }
+        unless postprocessing_disabled?
+          if @dtd[:tags][tag.name!].keys.include? :postprocessing
+            @dtd[:tags][tag.name!][:postprocessing].each { |processor| processor.process(self, tag) }
+          end
         end
       end
 
@@ -170,10 +247,12 @@ module ESS
       end
 
       def do_text_postprocessing_of text
-        text = text.to_s if text.class != String
-        if @dtd.include? :postprocessing_text
-          @dtd[:postprocessing_text].each do |processor|
-            text = processor.process text
+        unless postprocessing_disabled?
+          text = text.to_s if text.class != String
+          if @dtd.include? :postprocessing_text
+            @dtd[:postprocessing_text].each do |processor|
+              text = processor.process text
+            end
           end
         end
         text

data/lib/ess/ess.rb

@@ -1,8 +1,306 @@
+require 'time'
+
 module ESS
   class ESS < Element
     def initialize
       super :ess, DTD::ESS
     end
+
+    ##
+    # Returns the next n events from the moment specified in the second
+    # optional argument.
+    #
+    # === Parameters
+    #
+    # [n = 10] how many coming events should be returned
+    # [start_time] only events hapenning after this time will be considered
+    #
+    # === Returns
+    #
+    # A list of hashes, sorted by event start time, each hash having
+    # two keys:
+    #
+    # [:time] start time of the event
+    # [:feed] feed describing the event
+    #
+    def find_coming n=10, start_time=nil
+      start_time = Time.now if start_time.nil?
+      feeds = []
+      channel.feed_list.each do |feed|
+        feed.dates.item_list.each do |item|
+          if item.type_attr == "standalone"
+            feeds << { :time => Time.parse(item.start.text!), :feed => feed }
+          elsif item.type_attr == "recurrent"
+            moments = parse_recurrent_date_item(item, n, start_time)
+            moments.each do |moment|
+              feeds << { :time => moment, :feed => feed }
+            end
+          elsif item.type_attr == "permanent"
+            start = Time.parse(item.start.text!)
+            if start > start_time
+              feeds << { :time => start, :feed => feed }
+            else
+              feeds << { :time => start_time, :feed => feed }
+            end
+          else
+            raise DTD::InvalidValueError, "the \"#{item.type_attr}\" is not valid for a date item type attribute"
+          end
+        end
+      end
+      feeds = feeds.delete_if { |x| x[:time] < start_time }
+      feeds.sort! { |x, y| x[:time] <=> y[:time] }
+      return feeds[0..n-1]
+    end
+
+    ##
+    # Returns all events starting after the time specified by the first
+    # parameter and before the time specified by the second parameter,
+    # which accept regular Time objects.
+    #
+    # === Parameters
+    #
+    # [start_time] will return only events starting after this moment
+    # [end_time] will return only events starting before this moment
+    #
+    # === Returns
+    #
+    # A list of hashes, sorted by event start time, each hash having
+    # two keys:
+    #
+    # [:time] start time of the event
+    # [:feed] feed describing the event
+    #
+    def find_between start_time, end_time
+      feeds = []
+      channel.feed_list.each do |feed|
+        feed.dates.item_list.each do |item|
+          if item.type_attr == "standalone"
+            feed_start_time = Time.parse(item.start.text!)
+            if feed_start_time.between?(start_time, end_time)
+              feeds << { :time => feed_start_time, :feed => feed }
+            end
+          elsif item.type_attr == "recurrent"
+            moments = parse_recurrent_date_item(item, end_time, start_time)
+            moments.each do |moment|
+              if moment.between?(start_time, end_time)
+                feeds << { :time => moment, :feed => feed }
+              end
+            end
+          elsif item.type_attr == "permanent"
+            start = Time.parse(item.start.text!)
+            unless start > end_time
+              if start > start_time
+                feeds << { :time => start, :feed => feed }
+              else
+                feeds << { :time => start_time, :feed => feed }
+              end
+            end
+          else
+            raise DTD::InvalidValueError, "the \"#{item.type_attr}\" is not valid for a date item type attribute"
+          end
+        end
+      end
+      feeds.sort! { |x, y| x[:time] <=> y[:time] }
+    end
+
+    private
+
+      WEEK_DAYS = {
+        'monday' => 1,
+        'tuesday' => 2,
+        'wednesday' => 3,
+        'thursday' => 4,
+        'friday' => 5,
+        'saturday' => 6,
+        'sunday' => 7
+      }
+
+      INC_FUNCS = {
+        "year" => lambda { |time| inc_year(time) },
+        "month" => lambda { |time| inc_month(time) },
+        "week" => lambda { |time| inc_week(time) },
+        "day" => lambda { |time| inc_day(time) },
+        "hour" => lambda { |time| inc_hour(time) }
+      }
+
+      def parse_recurrent_date_item item, n_or_end_date, start_time
+        current = first = Time.parse(item.start.text!)
+        inc_period_func = INC_FUNCS[item.unit_attr || "hour"]
+        interval = (item.interval_attr == "") ? 1 : item.interval_attr.to_i
+        all = []
+        if item.limit_attr.length == 0
+          break_func = (n.class == FixNum) ? lambda { all.length >= n_or_end_date } : lambda { current > n_or_end_date }
+          while true
+            parse_unit(item, current, all)
+            interval.times do current = inc_period_func.call(current) end
+            all = all.delete_if { |x| x[:time] < start_time }
+            break if break_func.call
+          end
+        else
+          item.limit_attr.to_i.times do
+            parse_unit(item, current, all)
+            interval.times do current = inc_period_func.call(current) end
+          end
+        end
+        all = all.delete_if { |time| time < start_time || time < first }
+      end
+
+      def parse_unit item, current, all
+        case item.unit_attr.downcase
+        when "year"
+          all << current
+        when "month"
+          weeks = item.selected_week_attr.downcase.split(",")
+          days = item.selected_day_attr.downcase.split(",")
+          if weeks.any?
+            if days.none?
+              days = WEEK_DAYS.keys
+            end
+          end
+          if weeks.none?
+            if days.any?
+              weeks = ["first", "second", "third", "fourth", "last"]
+            end
+          end
+          if days.any?
+            days.each do |day|
+              if WEEK_DAYS.include? day
+                parse_month_week_day(day, current, weeks, all)
+              elsif day.to_i.to_s == day
+                parse_month_day(day, current, all)
+              else
+                raise InvalidValueError, "the \"#{day}\" value is not valid for a date item selected_day attribute"
+              end
+            end
+          else
+            all << current
+          end
+        when "week"
+          days = item.selected_day_attr.split(",")
+          if days.none?
+            all << current
+          else
+            days.each { |day| parse_week_day(day, current, all) }
+          end
+        when "day"
+          all << current
+        when "hour"
+          all << current
+        else
+          raise InvalidValueError, "the \"#{item.unit_attr}\" is not valid for a date item unit attribute"
+        end
+      end
+
+      def parse_month_week_day day, current, weeks, all
+        weeks.each do |week|
+          case week
+          when "first"
+            current = change_time(current, :day => 1)
+          when "second"
+            current = change_time(current, :day => 8)
+          when "third"
+            current = change_time(current, :day => 15)
+          when "fourth"
+            current = change_time(current, :day => 22)
+          when "last"
+            current = change_time(current, :day => (days_in_month(current) - 6))
+          else
+            raise InvalidValueError, "the \"#{item.unit_attr}\" is not valid for a date item unit attribute"
+          end
+          all << change_time(current, :day => ((7+ WEEK_DAYS[day] - current.wday) % 7 + current.day))
+        end
+      end
+
+      def change_time time, options
+        sec = options[:sec] || time.sec
+        min = options[:min] || time.min
+        hour = options[:hour] || time.hour
+        day = options[:day] || time.day
+        month = options[:month] || time.month
+        year = options[:year] || time.year
+        time.class.new(year, month, day, hour, min, sec, time.utc_offset)
+      end
+
+      def days_in_month time
+        self.class.days_in_month time
+      end
+
+      def self.days_in_month time
+        case time.month
+        when 1, 3, 5, 7, 8, 10, 12
+          31
+        when 2
+          if time.year % 4 == 0
+            29
+          else
+            28
+          end
+        when 4, 6, 9, 11
+          30
+        end
+      end
+
+      def parse_month_day day, current, all
+        all << change_time(current, :day => day)
+      end
+
+      def parse_week_day day, current, all
+        day = day.downcase
+        current_wday = current.wday
+        current_wday = 7 if current_wday == 0
+        if WEEK_DAYS.keys.include? day
+          next_day = current.day + WEEK_DAYS[day] - current_wday
+        elsif day.to_i.to_s == day
+          next_day = current.day + day.to_i - current_wday
+        else
+          raise InvalidValueError, "the \"#{day}\" value is not valid for a date item selected_day attribute"
+        end
+        month = current.month
+        if next_day > days_in_month(current)
+          next_day -= days_in_month(current)
+          month += 1
+        end
+        year = current.year
+        if month > 12
+          month -= 12
+          year += 1
+        end
+        all << change_time(current, :year => year, :month => month, :day => next_day)
+      end
+
+      def self.inc_year time
+        if time.year % 4 == 0
+          time + 60*60*24*366
+        else
+          time + 60*60*24*365
+        end
+      end
+
+      def self.inc_month time
+        increment = nil
+        if time.month == 2
+          if time.year % 4 == 0
+            increment = 60*60*24*29
+          else
+            increment = 60*60*24*28
+          end
+        else
+          increment = 60*60*24*days_in_month(time)
+        end
+        time + increment
+      end
+
+      def self.inc_week time
+        time + 60*60*24*7
+      end
+
+      def self.inc_day
+        time + 60*60*24
+      end
+
+      def self.inc_hour
+        kime + 3600
+      end
   end
 end