ri_cal 0.5.0

data/lib/ri_cal/core_extensions/time/conversions.rb

@@ -0,0 +1,61 @@
+module RiCal
+  module CoreExtensions #:nodoc:
+    module Time #:nodoc:
+      #- ©2009 Rick DeNatale
+      #- All rights reserved. Refer to the file README.txt for the license
+      #
+      module Conversions
+        # Return an RiCal::PropertyValue::DateTime representing the receiver
+        def to_ri_cal_date_time_value(timezone_finder = nil) #:nodoc:
+          RiCal::PropertyValue::DateTime.new(
+               timezone_finder, 
+               :value => strftime("%Y%m%dT%H%M%S"), 
+               :params => {"TZID" => self.tzid || :default})
+        end
+
+        alias_method :to_ri_cal_date_or_date_time_value, :to_ri_cal_date_time_value #:nodoc:
+        alias_method :to_ri_cal_occurrence_list_value, :to_ri_cal_date_time_value #:nodoc:
+
+        # Return the natural ri_cal_property for this object
+        def to_ri_cal_property_value(timezone_finder = nil) #:nodoc:
+          to_ri_cal_date_time_value(timezone_finder)
+        end
+        
+        # Return a copy of this object which will be interpreted as a floating time.
+        def with_floating_timezone
+          dup.set_tzid(:floating)
+        end
+        
+        unless defined? ActiveSupport
+          # Converts a Time object to a Date, dropping hour, minute, and second precision.
+          #
+          #   my_time = Time.now  # => Mon Nov 12 22:59:51 -0500 2007
+          #   my_time.to_date     # => Mon, 12 Nov 2007
+          #
+          #   your_time = Time.parse("1/13/2009 1:13:03 P.M.")  # => Tue Jan 13 13:13:03 -0500 2009
+          #   your_time.to_date                                 # => Tue, 13 Jan 2009
+          def to_date
+            ::Date.new(year, month, day)
+          end
+
+          # A method to keep Time, Date and DateTime instances interchangeable on conversions.
+          # In this case, it simply returns +self+.
+          def to_time
+            self
+          end
+
+          # Converts a Time instance to a Ruby DateTime instance, preserving UTC offset.
+          #
+          #   my_time = Time.now    # => Mon Nov 12 23:04:21 -0500 2007
+          #   my_time.to_datetime   # => Mon, 12 Nov 2007 23:04:21 -0500
+          #
+          #   your_time = Time.parse("1/13/2009 1:13:03 P.M.")  # => Tue Jan 13 13:13:03 -0500 2009
+          #   your_time.to_datetime                             # => Tue, 13 Jan 2009 13:13:03 -0500
+          def to_datetime
+            ::DateTime.civil(year, month, day, hour, min, sec, Rational(utc_offset, 86400))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ri_cal/core_extensions/time/tzid_access.rb

@@ -0,0 +1,50 @@
+module RiCal
+  module CoreExtensions #:nodoc:
+    module Time #:nodoc:
+      #- ©2009 Rick DeNatale
+      #- All rights reserved. Refer to the file README.txt for the license
+      #
+      # Provides a tzid attribute for ::Time and ::DateTime
+      module TzidAccess
+        # The tzid attribute is used by RiCal, it should be a valid timezone identifier within a calendar,
+        # :floating to indicate a floating time, or nil to use the default timezone in effect
+        #
+        # See PropertyValue::DateTime#default_tzid= and Component::Calendar#tzid=
+        attr_accessor :tzid
+
+        # Convenience method, sets the tzid and returns the receiver
+        def set_tzid(time_zone_identifier)
+          self.tzid = time_zone_identifier
+          self
+        end
+
+        # Predicate indicating whether or not the instance represents a floating time
+        def has_floating_timezone?
+          tzid == :floating
+        end
+
+      end
+    end
+  end
+
+  module TimeWithZoneExtension #:nodoc:
+    def tzid
+      utc? ? "UTC" : time_zone.tzinfo.identifier
+    end
+
+    # Predicate indicating whether or not the instance represents a floating time
+    def has_floating_timezone?
+      false
+    end
+
+    def to_ri_cal_date_time_value(timezone_finder=nil)
+      ::RiCal::PropertyValue::DateTime.new(timezone_finder, :params => {"TZID" => tzid}, :value => strftime("%Y%m%dT%H%M%S"))
+    end
+    alias_method :to_ri_cal_date_or_date_time_value, :to_ri_cal_date_time_value
+    alias_method :to_ri_cal_occurrence_list_value, :to_ri_cal_date_time_value
+  end
+end
+
+if RiCal::TimeWithZone
+  RiCal::TimeWithZone.class_eval {include RiCal::TimeWithZoneExtension}
+end

data/lib/ri_cal/core_extensions/time/week_day_predicates.rb

@@ -0,0 +1,88 @@
+module RiCal
+  module CoreExtensions #:nodoc:
+    module Time #:nodoc:
+      #- ©2009 Rick DeNatale
+      #- All rights reserved. Refer to the file README.txt for the license
+      #
+      # Provide predicate and related methods for use by the RiCal gem
+      # This module is included by Time, Date, and DateTime
+      module WeekDayPredicates
+        
+        # Determine the equivalent time on the day which falls on a particular weekday of the same year as the receiver
+        #
+        # == Parameters
+        # n:: the ordinal number being requested
+        # which_wday:: the weekday using Ruby time conventions, i.e. 0 => Sunday, 1 => Monday, ...
+        
+        # e.g. to obtain the 2nd Monday of the receivers year use
+        #
+        #   time.nth_wday_in_year(2, 1)
+        def nth_wday_in_year(n, which_wday, for_time = self)
+          if n > 0
+            first_of_year = for_time.to_ri_cal_property_value.change(:month => 1, :day => 1)
+            first_in_year = first_of_year.advance(:days => (which_wday - first_of_year.wday + 7) % 7)
+            first_in_year.advance(:days => (7*(n - 1)))
+          else
+            december25 = for_time.to_ri_cal_property_value.change(:month => 12, :day => 25)
+            last_in_year = december25.advance(:days => (which_wday - december25.wday + 7) % 7)
+            last_in_year.advance(:days => (7 * (n + 1)))
+          end
+        end
+        
+        # A predicate to determine whether or not the receiver falls on a particular weekday of its year.
+        # 
+        # See #nth_wday_in_year
+        #
+        # == Parameters
+        # n:: the ordinal number being requested
+        # which_wday:: the weekday using Ruby time conventions, i.e. 0 => Sunday, 1 => Monday, ...
+        def nth_wday_in_year?(n, which_wday)
+          target = nth_wday_in_year(n, which_wday)
+          [self.year, self.mon, self.day] == [target.year, target.mon, target.day]
+        end
+
+        # Determine the day which falls on a particular weekday of the same month as the receiver
+        #
+        # == Parameters
+        # n:: the ordinal number being requested
+        # which_wday:: the weekday using Ruby time conventions, i.e. 0 => Sunday, 1 => Monday, ...
+        
+        # e.g. to obtain the 3nd Tuesday of the receivers month use
+        #
+        #   time.nth_wday_in_month(2, 2)
+        def nth_wday_in_month(n, which_wday, for_time = self)
+          first_of_month = for_time.to_ri_cal_property_value.change(:day => 1)
+          first_in_month = first_of_month.advance(:days => (which_wday - first_of_month.wday))
+          first_in_month = first_in_month.advance(:days => 7) if first_in_month.month != first_of_month.month
+          if n > 0
+            first_in_month.advance(:days => (7*(n - 1)))
+          else
+            possible = first_in_month.advance(:days => 21)
+            possible = possible.advance(:days => 7) while possible.month == first_in_month.month
+            last_in_month = possible.advance(:days => - 7)
+            (last_in_month.advance(:days => - (7*(n.abs - 1))))
+          end
+        end
+              
+        # A predicate to determine whether or not the receiver falls on a particular weekday of its month.
+        #
+        # == Parameters
+        # n:: the ordinal number being requested
+        # which_wday:: the weekday using Ruby time conventions, i.e. 0 => Sunday, 1 => Monday, ...
+        def nth_wday_in_month?(n, which_wday)
+          target = nth_wday_in_month(n, which_wday)
+          [self.year, self.month, self.day] == [target.year, target.month, target.day]
+        end
+        
+        # Return a DateTime which is the beginning of the first day on or before the receiver
+        # with the specified wday
+        def start_of_week_with_wkst(wkst)
+           wkst ||= 1
+           date = ::Date.civil(self.year, self.month, self.day)
+           date -= 1 while date.wday != wkst
+           date
+        end
+      end
+    end
+  end
+end

data/lib/ri_cal/floating_timezone.rb

@@ -0,0 +1,32 @@
+module RiCal
+  #- ©2009 Rick DeNatale
+  #- All rights reserved. Refer to the file README.txt for the license
+  #
+  # FloatingTimezone represents the 'time zone' for a time or date time with no timezone
+  # Times with floating timezones are always interpreted in the timezone of the observer
+  class FloatingTimezone
+
+    def self.identifier #:nodoc:
+      nil
+    end
+
+    def self.tzinfo_timezone #:nodoc:
+      nil
+    end
+
+  def self.rational_utc_offset(local) #:nodoc:
+    Rational(0, 24)
+  end
+
+    # Return the time unchanged
+    def self.utc_to_local(time)
+      time.with_floating_timezone.to_ri_cal_date_time_value
+    end
+
+    # Return the time unchanged
+    def self.local_to_utc(time)
+      time.with_floating_timezone.to_ri_cal_date_time_value
+    end
+  end
+
+end

data/lib/ri_cal/invalid_property_value.rb

@@ -0,0 +1,8 @@
+module RiCal
+  #- ©2009 Rick DeNatale
+  #- All rights reserved. Refer to the file README.txt for the license
+  #
+  # An InvalidPropertyValue error is raised when an improper value is assigned to a property
+  class InvalidPropertyValue < StandardError
+  end
+end

data/lib/ri_cal/invalid_timezone_identifer.rb

@@ -0,0 +1,20 @@
+module RiCal
+  #- ©2009 Rick DeNatale
+  #- All rights reserved. Refer to the file README.txt for the license
+  #
+  # An InvalidTimezoneIdentifier error is raised when a DATETIME property with an invalid timezone is
+  # involved in a timezone conversion operation
+  #
+  # Rather than attempting to detect invalid timezones immediately the detection is deferred to avoid problems
+  # such as importing a calendar which has forward reference to VTIMEZONE components.
+  class InvalidTimezoneIdentifier < StandardError
+    
+    def self.not_found_in_calendar(identifier) #:nodoc:
+      new("#{identifier.inspect} is not the identifier of a VTIMEZONE component of this calendar")
+    end
+    
+    def self.invalid_tzinfo_identifier(identifier) #:nodoc:
+      new("#{identifier.inspect} is not known to the tzinfo database")
+    end
+  end
+end

data/lib/ri_cal/occurrence_enumerator.rb

@@ -0,0 +1,206 @@
+module RiCal
+  #- ©2009 Rick DeNatale
+  #- All rights reserved. Refer to the file README.txt for the license
+  #
+  # OccurrenceEnumerator provides common methods for CalendarComponents that support recurrence
+  # i.e. Event, Journal, Todo, and TimezonePeriod
+  module OccurrenceEnumerator
+    
+    include Enumerable
+
+    def default_duration # :nodoc:
+      dtend && dtstart.to_ri_cal_date_time_value.duration_until(dtend.to_ri_cal_date_time_value)
+    end
+
+    def default_start_time # :nodoc:
+      dtstart && dtstart.to_ri_cal_date_time_value
+    end
+
+    class EmptyRulesEnumerator # :nodoc:
+      def self.next_occurrence
+        nil
+      end
+      
+      def self.bounded?
+        true
+      end
+      
+      def self.empty?
+        true
+      end
+    end
+    
+    # OccurrenceMerger takes multiple recurrence rules and enumerates the combination in sequence. 
+    class OccurrenceMerger # :nodoc:
+      def self.for(component, rules)
+        if rules.nil? || rules.empty?
+          EmptyRulesEnumerator
+        elsif rules.length == 1
+          rules.first.enumerator(component)
+        else
+          new(component, rules)
+        end
+      end
+      
+      attr_accessor :enumerators, :nexts
+      
+      def initialize(component, rules)
+        self.enumerators = rules.map {|rrule| rrule.enumerator(component)}
+        @bounded = enumerators.all? {|enumerator| enumerator.bounded?}
+        @empty = enumerators.all? {|enumerator| enumerator.empty?}
+        self.nexts = @enumerators.map {|enumerator| enumerator.next_occurrence}
+      end
+      
+      def empty?
+        @empty
+      end
+      
+      # return the earliest of each of the enumerators next occurrences
+      def next_occurrence
+        result = nexts.compact.sort.first
+        if result
+          nexts.each_with_index { |datetimevalue, i| @nexts[i] = @enumerators[i].next_occurrence if result == datetimevalue }
+        end
+        result
+      end
+      
+      def bounded?
+        @bounded
+      end
+    end
+    
+    # EnumerationInstance holds the values needed during the enumeration of occurrences for a component.
+    class EnumerationInstance # :nodoc:
+      include Enumerable
+      
+      def initialize(component, options = {})
+        @component = component
+        @start = options[:starting]
+        @cutoff = options[:before]
+        @count = options[:count]
+        @rrules = OccurrenceMerger.for(@component, [@component.rrule_property, @component.rdate_property].flatten.compact)
+        @exrules = OccurrenceMerger.for(@component, [@component.exrule_property, @component.exdate_property].flatten.compact)
+      end
+      
+      # return the next exclusion which starts at the same time or after the start time of the occurrence
+      # return nil if this exhausts the exclusion rules
+      def exclusion_for(occurrence)
+        while (@next_exclusion && @next_exclusion.dtstart < occurrence.dtstart)
+          @next_exclusion = @exrules.next_occurrence
+        end
+        @next_exclusion
+      end
+
+      # TODO: Need to research this, I beleive that this should also take the end time into account,
+      #       but I need to research
+      def exclusion_match?(occurrence, exclusion)
+        exclusion && (occurrence.dtstart == exclusion.dtstart)
+      end
+      
+      # Also exclude occurrences before the :starting date_time
+      def exclude?(occurrence)
+        exclusion_match?(occurrence, exclusion_for(occurrence)) ||
+          (@start && occurrence.dtstart.to_datetime < @start)
+      end
+      
+      # yield each occurrence to a block
+      # some components may be open-ended, e.g. have no COUNT or DTEND 
+      def each
+        if @rrules.empty?
+          yield @component
+        else
+          occurrence = @rrules.next_occurrence
+          yielded = 0
+          @next_exclusion = @exrules.next_occurrence
+          while (occurrence)
+            if (@cutoff && occurrence.dtstart.to_datetime >= @cutoff) || (@count && yielded >= @count)
+              occurrence = nil
+            else
+              unless exclude?(occurrence)
+                yielded += 1
+                yield @component.recurrence(occurrence)
+              end
+              occurrence = @rrules.next_occurrence
+            end
+          end
+        end
+      end
+      
+      def bounded?
+        @rrules.bounded? || @count || @cutoff
+      end
+      
+      def to_a
+        raise ArgumentError.new("This component is unbounded, cannot produce an array of occurrences!") unless bounded?
+        super
+      end
+      
+      alias_method :entries, :to_a
+    end
+    
+    # return an array of occurrences according to the options parameter.  If a component is not bounded, and
+    # the number of occurrences to be returned is not constrained by either the :before, or :count options
+    # an ArgumentError will be raised.
+    #
+    # The components returned will be the same type as the receiver, but will have any recurrence properties
+    # (rrule, rdate, exrule, exdate) removed since they are single occurrences, and will have the recurrence-id
+    # property set to the occurrences dtstart value. (see RFC 2445 sec 4.8.4.4 pp 107-109)
+    #
+    # parameter options:
+    # * :starting:: a Date, Time, or DateTime, no occurrences starting before this argument will be returned
+    # * :before:: a Date, Time, or DateTime, no occurrences starting on or after this argument will be returned. 
+    # * :count:: an integer which limits the number of occurrences returned.
+    def occurrences(options={})
+      EnumerationInstance.new(self, options).to_a    
+    end
+    
+    # execute the block for each occurrence
+    def each(&block) # :yields: Component
+      EnumerationInstance.new(self).each(&block)
+    end
+    
+    # A predicate which determines whether the component has a bounded set of occurrences
+    def bounded?
+      EnumerationInstance.new(self).bounded?
+    end
+    
+    # Return a array whose first element is a UTC DateTime representing the start of the first
+    # occurrence, and whose second element is a UTC DateTime representing the end of the last
+    # occurrence.
+    # If the receiver is not bounded then the second element will be nil.
+    #
+    # The purpose of this method is to provide values which may be used as database attributes so
+    # that a query can find all occurence enumerating components which may have occurrences within
+    # a range of times.
+    def zulu_occurrence_range
+      if bounded?
+        all = occurrences
+        first, last = all.first, all.last
+      else
+        first = occurrences(:count => 1).first
+        last = nil
+      end
+      [first.zulu_occurrence_range_start_time, last ? last.zulu_occurrence_range_finish_time : nil]
+    end
+    
+    def set_occurrence_properties!(occurrence) # :nodoc:
+      occurrence_end = occurrence.dtend
+      occurrence_start = occurrence.dtstart
+      @rrule_property = nil
+      @exrule_property = nil
+      @rdate_property = nil
+      @exdate_property = nil
+      @recurrence_id_property = occurrence_start
+      if @dtend_property && !occurrence_end
+        occurrence_end = occurrence_start + (@dtend_property - @dtstart_property)
+      end
+      @dtstart_property = dtstart_property.for_occurrence(occurrence_start)
+      @dtend_property = dtend_property.for_occurrence(occurrence_end) if @dtend_property
+      self      
+    end
+    
+    def recurrence(occurrence) # :nodoc:
+      result = self.dup.set_occurrence_properties!(occurrence)
+    end
+  end
+end