ess 0.9.3 → 1.0.0

data/lib/ess/examples.rb

@@ -1,5 +1,8 @@
 module ESS
   module Examples
+    ##
+    # Example feeds for documentation and testing.
+    #
 
     def self.from_essfeeds_org_home
       ess = Maker.make do |ess|
@@ -45,7 +48,7 @@ module ESS
               item.selected_day_attr "saturday,sunday"
 
               item.name "Match Date"
-              item.start "2011-12-13T18:30:02Z"
+              item.start "2011-12-17T18:30:02Z"
               item.duration "10800"
             end
 
@@ -129,7 +132,7 @@ module ESS
                 item.country_code "US"
                 item.logo "http://sample.com/logo_120x60.png"
                 item.icon "http://sample.com/icon_64x64.png"
-                item.email "contact@sample.com"
+                item.email "contact@example.com"
                 item.phone "+001 (646) 234-5566"
               end
 
@@ -261,7 +264,7 @@ module ESS
 
             feed.dates.add_item :type => "recurrent", :unit => "month", :limit => 6, :selected_day => "saturday", :selected_week => "first,last" do |item|
               item.name "Course the first and last Saturdays of every month"
-              item.start "2013-10-25T15:30:00Z"
+              item.start "2013-10-05T15:30:00Z"
               item.duration "21600"
             end
 

data/lib/ess/helpers.rb

@@ -3,6 +3,9 @@ require 'digest/md5'
 
 module ESS
   module Helpers
+    ##
+    # Generates an UUID with the prefix specified, using the kay passed to it.
+    #
     def self.uuid key=nil, prefix='ESSID:'
       new_id = nil
       if key.nil?

data/lib/ess/maker.rb

@@ -1,12 +1,37 @@
 module ESS
   class Maker
-    DEFAULT_OPTIONS = {
-      :version => "0.9",
-      :lang => "en",
-      :validate => true,
-      :push => false
-    }
 
+    ##
+    # Create a new ESS document. See README for examples on how it should
+    # be used.
+    #
+    # === Yields
+    #
+    # [ESS::ESS] object representing the "ess" root tag of an ESS document
+    #
+    # === Options
+    #
+    # Currently, the following options are defined:
+    #
+    # ==== :push
+    #
+    # Whether to push the resulting document to aggregators before returning
+    # from the method. Default is false.
+    #
+    # ==== :validate
+    #
+    # Validate resulting document before returning from the method. Default
+    # is true.
+    #
+    # ==== :version
+    #
+    # Set a different value for the "version" attribute of the "ess" tag.
+    # Default is "0.9".
+    #
+    # ==== :lang
+    #
+    # Set a value for the "lang" attribute of the "ess" tag. Default is "en".
+    #
     def self.make options={}, &block
       options = DEFAULT_OPTIONS.merge options
       ess = ESS.new
@@ -19,6 +44,15 @@ module ESS
       ess.push_to_aggregators(options) if options[:push] || options[:aggregators]
       return ess
     end
+
+    private
+
+      DEFAULT_OPTIONS = {
+        :version => "0.9",
+        :lang => "en",
+        :validate => true,
+        :push => false
+      }
   end
 end
 

data/lib/ess/parser.rb

@@ -0,0 +1,31 @@
+require "ess"
+require "rexml/document"
+
+module ESS
+  class Parser
+    def self.parse data
+      doc = REXML::Document.new data
+      ess = doc.root
+      if ess.nil?
+        raise ArgumentError, "the argument has to contain a valid xml document"
+      end
+      new_ess = ESS.new
+      new_ess.disable_postprocessing
+      parse_element(ess, new_ess)
+      new_ess.enable_postprocessing
+      new_ess
+    end
+
+    def self.parse_element element, new_element=nil
+      element.attributes.each_pair do |attr, value|
+        new_element.send(attr + "_attr", value)
+      end
+      element.elements.each do |element|
+        new_element.send("add_" + element.name, element.text) do |new_element|
+          parse_element element, new_element
+        end
+      end
+    end
+  end
+end
+

data/lib/ess/postprocessing.rb

@@ -4,6 +4,10 @@ require 'date'
 
 module ESS
   module Postprocessing
+    ##
+    # Varous classes for postprocessing tag values. Should not be used directly,
+    # instances of it's classes are part of the DTD.
+    #
     class FeedTitle
       def process feed_tag, title_tag
         feed_tag.id(title_tag.text!) if feed_tag.id.text! == ""

data/lib/ess/pusher.rb

@@ -5,15 +5,53 @@ require 'uri'
 
 module ESS
   module Pusher
+    ##
+    # Sets the default aggregator services. Accepts a list of links in strings.
+    #
     def self.aggregators= aggs
       raise ArgumentError, "this method requires a list of links" if aggs.class != Array
       @@aggregators = aggs
     end
 
+    ##
+    # Returns the aggregator services currently set as default.
+    #
     def self.aggregators
       @@aggregators ||= ["http://api.hypecal.com/v1/ess/aggregator.json"]
     end
 
+    ##
+    # Pushes the feed to aggregators.
+    #
+    # === Options
+    #
+    # ==== :data
+    #
+    # A string, with an XML document representing the feed that needs to be
+    # pushed.
+    #
+    # ==== :feed
+    #
+    # This is an alternative to the :data option. This method accepts the feed
+    # link instead of the whole document. The aggregator service will pull the
+    # feed using this link.
+    #
+    # ==== :request
+    #
+    # This should be the request object that generated this feed. It can be
+    # useful for the aggregator service to receive some of th information
+    # from this object for crawling purposes.
+    #
+    # ==== :aggregators
+    #
+    # Intead of using the default aggregator services, this options can be used
+    # to specify what aggregators should the document be pushed to.
+    #
+    # ==== :ignore_errors
+    #
+    # The method will ignore any response from the aggregator services if this
+    # option is true. Default is false.
+    #
     def self.push_to_aggregators options={}
       options = { :aggregators => Pusher::aggregators,
                   :feed => nil,

data/lib/ess/validation.rb

@@ -1,10 +1,20 @@
 require 'ess/helpers'
 require 'time'
+require 'resolv'
 
 module ESS
   module Validation
+    ##
+    # Varous classes for validation of tag values. Should not be used directly,
+    # instances of it's classes are part of the DTD.
+    #
 
     class ValidationError < StandardError
+      ##
+      # This exception is generated when the validator find an error
+      # in the document. It should contain a message describing what
+      # was the value which caused it to be raised.
+      #
     end
 
     class TextIsNotNull
@@ -17,7 +27,32 @@ module ESS
 
     class TextIsValidEmail
       def validate tag
-        # TODO: Doing this is not recommended, check if realy necessary
+        return if valid_domain?(tag.text!)
+        raise InvalidValueError, "the email \"#{tag.text!}\" could not be validated"
+      end
+
+      EMAIL_PATTERN = /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i
+      SERVER_TIMEOUT = 10
+
+      def valid_domain?(email)
+        domain = email.match(EMAIL_PATTERN)[2]
+        dns = Resolv::DNS.new
+        Timeout::timeout(SERVER_TIMEOUT) do
+
+          # Check the MX record
+          mx_records = dns.getresources(domain, Resolv::DNS::Resource::IN::MX)
+
+          mx_records.sort_by {|mx| mx.preference}.each do |mx|
+            a_records = dns.getresources(mx.exchange.to_s, Resolv::DNS::Resource::IN::A)
+            return true if a_records.any?
+          end
+
+           #Try a straight A record
+           a_records = dns.getresources(domain, Resolv::DNS::Resource::IN::A)
+           a_records.any?
+         end
+      rescue Timeout::Error, Errno::ECONNREFUSED
+        false
       end
     end
 

data/lib/ess/version.rb

@@ -1,3 +1,3 @@
 module ESS
-  VERSION = "0.9.3"
+  VERSION = "1.0.0"
 end

data/spec/ess/ess_spec.rb

@@ -0,0 +1,350 @@
+require 'spec_helper'
+
+module ESS
+  describe "ESS" do
+    let(:future_year) { Time.now.year + 2 }
+
+    context 'feed with one item with standalone date' do
+      let(:ess) do
+        ess = ESS.new
+        ess.channel.add_feed do |feed|
+          feed.title "Feed 1"
+          feed.dates.add_item do |item|
+            item.type_attr "standalone"
+            item.name "Date 1"
+            item.start Time.parse("#{future_year}-01-01T00:00:00Z")
+          end
+        end
+        ess
+      end
+
+      describe '#find_coming' do
+        it 'should return that one item in an array' do
+          feeds = ess.find_coming
+          feeds.length.should == 1
+          feeds[0][:feed].title.text!.should == "Feed 1"
+        end
+      end
+
+      describe '#find_between' do
+        it 'should return that one item in an array if it\'s between the two moments in time' do
+          feeds = ess.find_between(Time.parse("#{future_year-1}-12-31T23:59:00Z"), Time.parse("#{future_year}-01-01T00:01:00Z"))
+          feeds.length.should == 1
+          feeds[0][:feed].title.text!.should == "Feed 1"
+        end
+
+        it 'should return an empty array if the item event is not between the two moments in time' do
+          feeds = ess.find_between(Time.parse("#{future_year}-01-01T00:01:00Z"), Time.parse("#{future_year}-01-01T00:03:00Z"))
+          feeds.length.should == 0
+        end
+      end
+    end
+
+    context 'ESS channel with two feeds with future standalone dates' do
+      let(:ess) do
+        ess = ESS.new
+        ess.channel.add_feed do |feed|
+          feed.title "Feed 1"
+          feed.dates.add_item do |item|
+            item.type_attr "standalone"
+            item.name "Date 1"
+            item.start Time.parse("#{future_year}-01-01T00:00:00Z")
+          end
+        end
+        ess.channel.add_feed do |feed|
+          feed.title "Feed 2"
+          feed.dates.add_item do |item|
+            item.type_attr "standalone"
+            item.name "Date 1"
+            item.start Time.parse("#{future_year}-01-08T00:00:00Z")
+          end
+        end
+        ess
+      end
+
+      describe '#find_coming' do
+        it 'should return both items in an array if no parameters were specified' do
+          feeds = ess.find_coming
+          feeds.length.should == 2
+          feeds[0][:feed].title.text!.should == "Feed 1"
+          feeds[1][:feed].title.text!.should == "Feed 2"
+        end
+
+        it 'should return the first feed in an array if passed the number 1' do
+          feeds = ess.find_coming(1)
+          feeds.length.should == 1
+          feeds[0][:feed].title.text!.should == "Feed 1"
+        end
+
+        it 'should return both items in an array if passed the number 2' do
+          feeds = ess.find_coming(2)
+          feeds.length.should == 2
+          feeds[0][:feed].title.text!.should == "Feed 1"
+          feeds[1][:feed].title.text!.should == "Feed 2"
+        end
+
+        it 'should return both items in an array if passed the number 2, sorted by asc. date/time' do
+          feeds = ess.channel.feed_list
+          tmp1 = feeds[0]
+          tmp2 = feeds[1]
+          ess.channel.feed_list.clear
+          ess.channel.feed_list << tmp2
+          ess.channel.feed_list << tmp1
+          feeds = ess.find_coming(2)
+          feeds.length.should == 2
+          feeds[0][:feed].title.text!.should == "Feed 1"
+          feeds[1][:feed].title.text!.should == "Feed 2"
+        end
+        it 'should return both items in an array if passed the number 3' do
+          feeds = ess.find_coming(3)
+          feeds.length.should == 2
+          feeds[0][:feed].title.text!.should == "Feed 1"
+          feeds[1][:feed].title.text!.should == "Feed 2"
+        end
+      end
+
+      describe '#find_between' do
+        it 'should return an empty list if none of the events is between two moments in time' do
+          feeds = ess.find_between(Time.parse("#{future_year-1}-12-21T23:59:00Z"), Time.parse("#{future_year-1}-12-31T00:01:00Z"))
+          feeds.length.should == 0
+          feeds = ess.find_between(Time.parse("#{future_year}-01-10T23:59:00Z"), Time.parse("#{future_year}-01-13T00:01:00Z"))
+          feeds.length.should == 0
+        end
+
+        it 'should return the first feed if it is happening between the two dates' do
+          feeds = ess.find_between(Time.parse("#{future_year-1}-12-21T23:59:00Z"), Time.parse("#{future_year}-01-05T00:01:00Z"))
+          feeds.length.should == 1
+          feeds[0][:feed].title.text!.should == "Feed 1"
+        end
+
+        it 'should return the second feed if it is happening between the two dates' do
+          feeds = ess.find_between(Time.parse("#{future_year}-01-01T00:02:00Z"), Time.parse("#{future_year}-01-09T00:01:00Z"))
+          feeds.length.should == 1
+          feeds[0][:feed].title.text!.should == "Feed 2"
+        end
+
+        it 'should return both items if they both happen in the interval' do
+          feeds = ess.find_between(Time.parse("#{future_year}-01-01T00:00:00Z"), Time.parse("#{future_year}-01-09T00:01:00Z"))
+          feeds.length.should == 2
+          feeds[0][:feed].title.text!.should == "Feed 1"
+          feeds[1][:feed].title.text!.should == "Feed 2"
+        end
+      end
+    end
+
+    context 'one feed with two date items with standalone values' do
+      let(:ess) do
+        ess = ESS.new
+        ess.channel.add_feed do |feed|
+          feed.title "Feed 1"
+          feed.dates.add_item do |item|
+            item.type_attr "standalone"
+            item.name "Date 2"
+            item.start Time.parse("#{future_year}-01-01T00:15:00Z")
+          end
+          feed.dates.add_item do |item|
+            item.type_attr "standalone"
+            item.name "Date 1"
+            item.start Time.parse("#{future_year}-01-01T00:00:00Z")
+          end
+        end
+        ess
+      end
+
+      describe "#find_coming" do
+        it 'should return two items in a list, if no arguments are passed' do
+          ess.find_coming.length.should == 2
+        end
+
+        it 'should return one item in a list, if the only argument is a 1' do
+          ess.find_coming(1).length.should == 1
+        end
+
+        it 'should return a list of dicts, with keys :time and :feed' do
+          feeds = ess.find_coming
+          feeds.each do |feed|
+            feed[:time].should_not be_nil
+            feed[:feed].should_not be_nil
+          end
+        end
+
+        it 'should return a list of discts sorted by ascending order of time' do
+          feeds = ess.find_coming
+          feeds[0][:time].should == Time.parse("#{future_year}-01-01T00:00:00Z")
+          feeds[0][:feed].title.text!.should == "Feed 1"
+          feeds[1][:time].should == Time.parse("#{future_year}-01-01T00:15:00Z")
+          feeds[1][:feed].title.text!.should == "Feed 1"
+        end
+      end
+
+      describe "#find_between" do
+        it 'should return two items in a list, if both date items are within the time period' do
+          feeds = ess.find_between(Time.parse("#{future_year}-01-01T00:00:00Z"), Time.parse("#{future_year}-01-09T00:01:00Z"))
+          feeds.length == 2
+        end
+
+        it 'should return two hashes in a list, with :time and :feed values defined' do
+          feeds = ess.find_between(Time.parse("#{future_year}-01-01T00:00:00Z"), Time.parse("#{future_year}-01-09T00:01:00Z"))
+          feeds.each do |feed|
+            feed[:time].should_not be_nil
+            feed[:feed].should_not be_nil
+          end
+        end
+
+        it 'should return a list of dicts sorted by ascending order of time' do
+          feeds = ess.find_coming
+          feeds[0][:time].should == Time.parse("#{future_year}-01-01T00:00:00Z")
+          feeds[0][:feed].title.text!.should == "Feed 1"
+          feeds[1][:time].should == Time.parse("#{future_year}-01-01T00:15:00Z")
+          feeds[1][:feed].title.text!.should == "Feed 1"
+        end
+      end
+    end
+
+    context 'feed with one item with recurring date with a limit attribute' do
+      let(:ess) do
+        ess = ESS.new
+        ess.channel.add_feed do |feed|
+          feed.title "Feed 1"
+          feed.dates.add_item do |item|
+            item.type_attr "recurrent"
+            item.unit_attr "month"
+            item.limit_attr "5"
+            item.name "Date 1"
+            item.start Time.parse("#{future_year}-01-01T00:00:00Z")
+          end
+        end
+        ess
+      end
+
+      describe "#find_coming" do
+        it 'should return the array with as much elements, as there will be separate events' do
+          ess.find_coming.length.should == 5
+        end
+
+        it 'should return a list of feeds, sorted by starting date/time' do
+          feeds = ess.find_coming
+          feeds[0][:time].should == Time.parse("#{future_year}-01-01T00:00:00Z")
+          feeds[1][:time].should == Time.parse("#{future_year}-02-01T00:00:00Z")
+          feeds[2][:time].should == Time.parse("#{future_year}-03-01T00:00:00Z")
+          feeds[3][:time].should == Time.parse("#{future_year}-04-01T00:00:00Z")
+          feeds[4][:time].should == Time.parse("#{future_year}-05-01T00:00:00Z")
+        end
+      end
+
+      describe "#find_coming" do
+        it 'should return a list of event instances within time boundaries' do
+          feeds = ess.find_between(Time.parse("#{future_year}-02-11T00:00:00Z"), Time.parse("#{future_year}-07-11T12:00:00Z"))
+          feeds.length.should == 3
+          feeds[0][:time].should == Time.parse("#{future_year}-03-01T00:00:00Z")
+          feeds[1][:time].should == Time.parse("#{future_year}-04-01T00:00:00Z")
+          feeds[2][:time].should == Time.parse("#{future_year}-05-01T00:00:00Z")
+        end
+      end
+    end
+
+    context 'feed with one item with recurring date with a limit attribute and an interval attribute' do
+      let(:ess) do
+        ess = ESS.new
+        ess.channel.add_feed do |feed|
+          feed.title "Feed 1"
+          feed.dates.add_item do |item|
+            item.type_attr "recurrent"
+            item.unit_attr "month"
+            item.interval_attr "2"
+            item.limit_attr "5"
+            item.name "Date 1"
+            item.start Time.parse("#{future_year}-01-01T00:00:00Z")
+          end
+        end
+        ess
+      end
+
+      describe "#find_coming" do
+        it 'should return the array with as much elements, as there will be separate events' do
+          ess.find_coming.length.should == 5
+        end
+
+        it 'should return a list of feeds, sorted by starting date/time' do
+          feeds = ess.find_coming
+          feeds[0][:time].should == Time.parse("#{future_year}-01-01T00:00:00Z")
+          feeds[1][:time].should == Time.parse("#{future_year}-03-01T00:00:00Z")
+          feeds[2][:time].should == Time.parse("#{future_year}-05-01T00:00:00Z")
+          feeds[3][:time].should == Time.parse("#{future_year}-07-01T00:00:00Z")
+          feeds[4][:time].should == Time.parse("#{future_year}-09-01T00:00:00Z")
+        end
+      end
+
+      describe "#find_between" do
+        it 'should return a list of feeds between the two dates it received as parameters' do
+          feeds = ess.find_between(Time.parse("#{future_year}-03-11T00:00:00Z"), Time.parse("#{future_year}-10-11T00:00:00Z"))
+          feeds.length.should == 3
+          feeds[0][:time].should == Time.parse("#{future_year}-05-01T00:00:00Z")
+          feeds[1][:time].should == Time.parse("#{future_year}-07-01T00:00:00Z")
+          feeds[2][:time].should == Time.parse("#{future_year}-09-01T00:00:00Z")
+        end
+      end
+    end
+
+    context 'feed with one item with recurring date with a limit attribute and a selected_day attribute' do
+      let(:ess) do
+        ess = ESS.new
+        ess.channel.add_feed do |feed|
+          feed.title "Feed 1"
+          feed.dates.add_item do |item|
+            item.type_attr "recurrent"
+            item.unit_attr "month"
+            item.limit_attr "5"
+            item.selected_day_attr "2"
+            item.name "Date 1"
+            item.start Time.parse("#{future_year}-01-02T00:00:00Z")
+          end
+        end
+        ess
+      end
+
+      describe "#find_coming" do
+        it 'should return events only on those days specified in the selected_day attribute' do
+          feeds = ess.find_coming
+          feeds.length.should == 5
+          feeds[0][:time].should == Time.parse("#{future_year}-01-02T00:00:00Z")
+          feeds[1][:time].should == Time.parse("#{future_year}-02-02T00:00:00Z")
+          feeds[2][:time].should == Time.parse("#{future_year}-03-02T00:00:00Z")
+          feeds[3][:time].should == Time.parse("#{future_year}-04-02T00:00:00Z")
+          feeds[4][:time].should == Time.parse("#{future_year}-05-02T00:00:00Z")
+        end
+
+        it 'should support using day names' do
+          ess.channel.feed.dates.item.selected_day_attr "monday"
+          feeds = ess.find_coming(30)
+          feeds.length.should be > 19
+          feeds.length.should be < 26
+          feeds.each do |event|
+            event[:time].wday.should == 1
+          end
+        end
+      end
+
+      describe "#find_between" do
+        it 'should return events only on those days specified in the selected_day attribute' do
+          feeds = ess.find_between(Time.parse("#{future_year}-01-05 00:00"), Time.parse("#{future_year}-04-06T00:00:00Z"))
+          feeds.length.should == 3
+          feeds[0][:time].should == Time.parse("#{future_year}-02-02T00:00:00Z")
+          feeds[1][:time].should == Time.parse("#{future_year}-03-02T00:00:00Z")
+          feeds[2][:time].should == Time.parse("#{future_year}-04-02T00:00:00Z")
+        end
+
+        it 'should support using day names' do
+          ess.channel.feed.dates.item.selected_day_attr "monday"
+          feeds = ess.find_between(Time.parse("#{future_year}-02-01T00:00:00Z"), Time.parse("#{future_year}-04-30T00:00:00Z"))
+          feeds.length.should be > 11
+          feeds.length.should be < 16
+          feeds.each do |event|
+            event[:time].wday.should == 1
+          end
+        end
+      end
+    end
+  end
+end
+