demingfactor-ri_cal 0.9.0

data/lib/ri_cal/fast_date_time.rb

@@ -0,0 +1,234 @@
+module RiCal
+  #- ©2009 Rick DeNatale
+  #- All rights reserved. Refer to the file README.txt for the license
+  #
+  # FastDateTime mimics the Ruby Standard library DateTime class but avoids the use of Rational
+  # Instead of using a Rational for the utc offset, FastDateTime uses an integer seconds value
+  class FastDateTime
+    attr_accessor :date, :hour, :min, :sec, :offset, :secs_since_bod
+
+    SECONDS_IN_A_DAY = 60*60*24 unless defined? SECONDS_IN_A_DAY
+
+    include Comparable
+
+    def initialize(year, month, day, hour, min, sec, offset_seconds)
+      @date = Date.civil(year, month, day)
+      @secs_since_bod = hms_to_seconds(hour, min, sec)
+      @hour, @min, @sec, @offset = hour, min, sec, offset_seconds
+    end
+
+    def self.from_date_time(date_time)
+      new(date_time.year, date_time.month, date_time.day, date_time.hour, date_time.min, date_time.sec, (date_time.offset * SECONDS_IN_A_DAY).to_i)
+    end
+    
+    def self.from_time(time)
+      new(time.year, time.month, time.day, time.hour, time.min, time.sec, (time.utc_offset.offset * SECONDS_IN_A_DAY))
+    end
+    
+    def self.from_date(date)
+      new(date.year, date.month, date.day, 0, 0, 0, 0)
+    end
+    
+    def self.from_date_at_end_of_day(date)
+      new(date.year, date.month, date.day, 23, 59, 59, 0)
+    end
+
+    alias_method :utc_offset_seconds, :offset
+
+    def ical_str
+      "%04d%02d%02dT%02d%02d%02d" % [year, month, day, hour, min, sec]
+    end
+
+    def ical_date_str
+      "%04d%02d%02d" % [year, month, day]
+    end
+
+    def year
+      @date.year
+    end
+
+    def month
+      @date.month
+    end
+
+    alias_method :mon, :month
+
+    def day
+      @date.day
+    end
+    
+    def wday
+      @date.wday
+    end
+
+    def to_datetime
+      DateTime.civil(year, month, day, hour, min, sec, RiCal.RationalOffset[utc_offset_seconds])
+    end
+
+    def ==(other)
+      [date, secs_since_bod, offset] == [other.date, other.secs_since_bod, other.offset]
+    end
+
+    def <=> (other)
+      if FastDateTime === other
+        [date, secs_since_bod] <=> [other.date, other.secs_since_bod]
+      else
+        [year, month, day, hour, min, sec] <=> [other.year, other.month, other.day, other.hour, other.min, other.sec]
+      end
+    end
+
+    def to_s
+      "#{year}/#{month}/#{day} #{hour}:#{min}:#{sec} #{offset}"
+    end
+
+    # def jd
+    #   date.jd
+    # end
+    # 
+    def days_in_month
+      date.days_in_month
+    end
+
+    alias_method :inspect, :to_s
+
+    # Return a new FastDateTime based on the receiver but with changes specified by the options
+    def change(options)
+      FastDateTime.new(
+      options[:year]  || year,
+      options[:month] || month,
+      options[:day]   || day,
+      options[:hour]  || hour,
+      options[:min]   || (options[:hour] ? 0 : min),
+      options[:sec]   || ((options[:hour] || options[:min]) ? 0 : sec),
+      options[:offset]  || offset
+      )
+    end
+
+    # def new_offset(ofst)
+    #   if ofst == offset
+    #     self
+    #   else
+    #     advance(:seconds => offset - ofset, :offset => ofst)
+    #   end
+    # end
+
+    def utc
+      if offset == 0
+        self
+      else
+        advance(:seconds => -offset, :offset => 0)
+      end
+    end
+
+    def hms_to_seconds(hours, minutes, seconds)
+      seconds + 60 *(minutes + (60 * hours))
+    end
+
+    def seconds_to_hms(total_seconds)
+      sign = total_seconds <=> 0
+      remaining = total_seconds.abs
+      seconds = sign * (remaining % 60)
+      remaining = remaining / 60
+      minutes = sign * (remaining % 60)
+      [remaining / 60, minutes, seconds]
+    end
+
+    def adjust_day_delta(day_delta, new_secs_since_bod)
+      if new_secs_since_bod == 0
+        [day_delta, new_secs_since_bod]
+      elsif new_secs_since_bod > 0
+        [day_delta + (new_secs_since_bod / SECONDS_IN_A_DAY), new_secs_since_bod % SECONDS_IN_A_DAY]
+      else
+        [day_delta - (1 + new_secs_since_bod.abs / SECONDS_IN_A_DAY), 
+         SECONDS_IN_A_DAY - (new_secs_since_bod.abs % SECONDS_IN_A_DAY)]
+      end
+     end
+
+
+    def advance(options) # :nodoc:
+      new_date = @date
+      new_offset = options[:offset] || offset
+      month_delta = (options[:years] || 0) * 12 + (options[:months] || 0)
+      day_delta =   (options[:weeks] || 0) * 7 + (options[:days] || 0)
+      sec_delta = hms_to_seconds((options[:hours] || 0), (options[:minutes] || 0), (options[:seconds] || 0))
+      day_delta, new_secs_since_bod = *adjust_day_delta(day_delta, secs_since_bod + sec_delta)
+      new_hour, new_min, new_sec = *seconds_to_hms(new_secs_since_bod)
+      new_date = new_date >> month_delta unless month_delta == 0
+      new_date += day_delta unless day_delta == 0
+      FastDateTime.new(new_date.year, new_date.month, new_date.day, new_hour, new_min, new_sec, new_offset)
+    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)
+      first_of_month = 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
+    
+    # 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)
+      if n > 0
+        first_of_year = 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 = 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
+
+
+    # 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
+      date -= 1 while date.wday != wkst
+      date
+    end
+    
+    def iso_weeks_in_year(wkst)
+      @date.iso_weeks_in_year(wkst)
+    end
+    
+    def iso_year_start(wkst)
+      @date.iso_year_start(wkst)
+    end
+    
+    def iso_year_and_week_one_start(wkst)
+      @date.iso_year_and_week_one_start(wkst)
+    end
+    
+    def cmp_fast_date_time_value(other)
+      other <=> self
+    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:
+    @offset = RiCal.RationalOffset[0]
+  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_identifier.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,265 @@
+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)
+        @component = component
+        @rrules = OccurrenceMerger.for(@component, [@component.rrule_property, @component.rdate_property].flatten.compact)
+        @exrules = OccurrenceMerger.for(@component, [@component.exrule_property, @component.exdate_property].flatten.compact)
+        @yielded = 0
+      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 before_start?(occurrence)
+        (@start && occurrence.dtstart.to_datetime < @start) ||
+        @overlap_range && occurrence.before_range?(@overlap_range)
+      end
+
+      def next_occurrence
+        @next_exclusion ||= @exrules.next_occurrence
+        occurrence = nil
+
+        until occurrence
+          if (occurrence = @rrules.next_occurrence)
+            if exclusion_match?(occurrence, exclusion_for(occurrence))
+              occurrence = nil # Look for the next one
+            end
+          else
+            break
+          end
+        end
+        occurrence
+      end
+
+      def options_stop(occurrence)
+        occurrence != :excluded &&
+        (@cutoff && occurrence.dtstart.to_datetime >= @cutoff) || 
+        (@count && @yielded >= @count) ||
+        (@overlap_range && occurrence.after_range?(@overlap_range))
+      end
+
+
+      # yield each occurrence to a block
+      # some components may be open-ended, e.g. have no COUNT or DTEND
+      def each(options = nil)
+        process_options(options) if options
+        if @rrules.empty?
+          unless before_start?(@component)
+            yield @component unless options_stop(@component)
+          end
+        else
+          occurrence = next_occurrence
+          while (occurrence)
+            candidate = @component.recurrence(occurrence)
+            if options_stop(candidate)
+              occurrence = nil
+            else
+              unless before_start?(candidate)
+                @yielded += 1
+                yield candidate
+              end
+              occurrence = next_occurrence
+            end
+          end
+        end
+      end
+      
+      def bounded?
+        @rrules.bounded? || @count || @cutoff || @overlap_range
+      end
+      
+      def process_overlap_range(overlap_range)
+        if overlap_range
+          @overlap_range = [overlap_range.first.to_overlap_range_start, overlap_range.last.to_overlap_range_end]
+        end
+      end
+
+      def process_options(options)
+        @start = options[:starting] && options[:starting].to_datetime
+        @cutoff = options[:before] && options[:before].to_datetime
+        @overlap_range = process_overlap_range(options[:overlapping])
+        @count = options[:count]
+      end
+
+      def to_a(options = {})
+        process_options(options)
+        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.
+    # * :overlapping:: a two element array of Dates, Times, or DateTimes, assumed to be in chronological order. Only occurrences which are either totally or partially within the range will be returned.
+    def occurrences(options={})
+      enumeration_instance.to_a(options)
+    end
+
+    # TODO: Thread safe?
+    def enumeration_instance #:nodoc:
+      EnumerationInstance.new(self)
+    end
+    
+    def before_range?(overlap_range)
+      finish = finish_time
+      !finish_time || finish_time < overlap_range.first
+    end
+
+    def after_range?(overlap_range)
+      start = start_time
+      !start || start > overlap_range.last
+    end
+    
+    # execute the block for each occurrence
+    def each(&block) # :yields: Component
+      enumeration_instance.each(&block)
+    end
+
+    # A predicate which determines whether the component has a bounded set of occurrences
+    def bounded?
+      enumeration_instance.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 || @dtstart_property).for_occurrence(occurrence_end) if occurrence_end
+      self
+    end
+
+    def recurrence(occurrence) # :nodoc:
+      result = self.dup.set_occurrence_properties!(occurrence)
+    end
+    
+    def recurs?
+      @rrule_property && @rrule_property.length > 0 || @rdate_property && @rdate_property.length > 0
+    end
+
+  end
+end

data/lib/ri_cal/occurrence_period.rb

@@ -0,0 +1,17 @@
+module RiCal
+  class OccurrencePeriod
+    attr_reader :dtstart, :dtend
+    def initialize(dtstart, dtend)
+      @dtstart = dtstart
+      @dtend = dtend
+    end
+    
+    def to_s
+      "op:#{dtstart}-#{dtend}"
+    end
+    
+    def <=>(other)
+      [dtstart, dtend] <=> [other.dtstart, other.dtend]
+    end
+  end
+end