rubyredrick-ri_cal 0.0.2

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

@@ -0,0 +1,153 @@
+module RiCal
+  module CoreExtensions #:nodoc:
+    module Time #:nodoc:
+      #- ©2009 Rick DeNatale
+      #- All rights reserved. Refer to the file README.txt for the license
+      #
+      # Provide calculation methods for use by the RiCal gem
+      # This module is included by Time, Date, and DateTime
+      module Calculations
+        # A predicate method used to determine if the receiver is within a leap year
+        def leap_year?
+          year % 4 == 0 && (year % 400 == 0 || year % 100 != 0)
+        end 
+
+        # Return the number of days in the month which includes the receiver
+        def days_in_month
+          raw = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][self.month]
+          self.month == 2 && leap_year? ? raw + 1 : raw
+        end
+
+        # Return the date on which the first iso week with a given starting week day occurs
+        # for a given iso year
+        # 
+        #
+        # From RFC 2445 page 43:
+        # A week is defined as a seven day period, starting on the day of the week defined to be the
+        # week start (see WKST). Week number one of the calendar year is the first week which contains 
+        # at least four (4) days in that calendar
+        # year.
+        #
+        # == parameters
+        # year:: the iso year
+        # wkst:: an integer representing the day of the week on which weeks are deemed to start. This uses
+        # the ruby convention where 0 represents Sunday.
+        def self.iso_week_one(year, wkst)
+          # 
+          # Note that wkst uses the ruby definition, with Sunday = 0 
+          #
+          # A good article about calculating ISO week number is at
+          # http://www.boyet.com/Articles/PublishedArticles/CalculatingtheISOweeknumb.html
+          #
+          # RFC 2445 generalizes the notion of ISO week by allowing the start of the week to vary.
+          # In order to adopt the algorithm in the referenced article, we must determine, for each
+          # wkst value, the day in January which must be contained in week 1 of the year.
+          # 
+          # For a given wkst week 1 for a year is the first week which
+          #   1) Starts with a day with a wday of wkst
+          #   2) Contains a majority (4 or more) of days in that year
+          # 
+          # If end of prior Dec, start of Jan          Week 1 starts on For WKST =
+
+          # MO TU WE TH FR SA SU MO TU WE TH FR SA SU  MO    TU    WE    TH    FR    SA    SU      
+          # 01 02 03 04 05 06 07 08 09 10 11 12 13 14 01-07 02-08 03-09 04-10 05-11 06-12 07-13
+          # 31 01 02 03 04 05 06 07 08 09 10 11 12 13 31-06 01-07 02-08 03-09 04-10 05-11 06-12
+          # 30 31 01 02 03 04 05 06 07 08 09 10 11 12 30-05 31-06 01-07 02-08 03-09 04-10 05-11
+          # 29 30 31 01 02 03 04 05 06 07 08 09 10 11 29-04 30-05 31-06 01-07 02-08 03-09 04-10
+          # 28 29 30 31 01 02 03 04 05 06 07 08 09 10 04-10 29-04 30-05 31-06 01-07 02-08 03-09
+          # 27 28 29 30 31 01 02 03 04 05 06 07 08 09 03-09 04-10 29-04 30-05 31-06 01-07 02-08
+          # 26 27 28 29 30 31 01 02 03 04 05 06 07 08 02-08 03-09 04-10 29-04 30-05 31-06 01-07
+          # 25 26 27 28 29 30 31 01 02 03 04 05 06 07 01-07 02-08 03-09 04-10 29-04 30-05 31-06
+          #                     Week 1 must contain     4     4     4     4     ?     ?     ?  
+          #
+          # So for a wkst of FR, SA, or SU, there is no date which MUST be contained in the 1st week
+          # We'll have to brute force that
+          if (1..4).include?(wkst)
+            # return the date of the wkst day which is less than or equal to jan4th
+            jan4th = ::Date.new(year, 1, 4)
+            result = jan4th - (convert_wday(jan4th.wday) - convert_wday(wkst))
+          else
+            # return the date of the wkst day which is greater than or equal to Dec 31 of the prior year
+            dec29th = ::Date.new(year-1, 12, 29)
+            result = dec29th + convert_wday(wkst) - convert_wday(dec29th.wday)
+          end
+          result
+        end
+
+        # Convert the receivers wday to RFC 2445 format.  Whereas the Ruby time/date classes use
+        # 0 to represent Sunday, RFC 2445 uses 7.
+        def self.convert_wday(wday)
+          wday == 0 ? 7 : wday
+        end
+
+        # Return an array containing the iso year and iso week number for the receiver.
+        # Note that the iso year may be the year before or after the calendar year containing the receiver.
+        # == parameter
+        # wkst:: an integer representing the day of the week on which weeks are deemed to start. This uses
+        # the ruby convention where 0 represents Sunday.
+        def iso_year_and_week_one_start(wkst)
+          iso_year = self.year
+          date = ::Date.new(self.year, self.month, self.mday)
+          if (date >= ::Date.new(iso_year, 12, 29))
+            week_one_start =  Calculations.iso_week_one(iso_year + 1, wkst)
+            if date < week_one_start
+              week_one_start = Calculations.iso_week_one(iso_year, wkst)
+            else
+              iso_year += 1
+            end
+          else
+            week_one_start = Calculations.iso_week_one(iso_year, wkst)
+            if (date < week_one_start)
+              iso_year -= 1
+              week_one_start = Calculations.iso_week_one(iso_year, wkst)
+            end
+          end
+          [iso_year, week_one_start]
+        end
+
+        def iso_year_and_week_num(wkst) #:nodoc:
+          iso_year, week_one_start = *iso_year_and_week_one_start(wkst)
+          [iso_year, (::Date.new(self.year, self.month, self.mday) - week_one_start).to_i / 7 + 1]
+        end
+
+        # return the number of weeks in the the iso year containing the receiver
+        # == parameter
+        # wkst:: an integer representing the day of the week on which weeks are deemed to start. This uses
+        # the ruby convention where 0 represents Sunday.
+        def iso_weeks_in_year(wkst)
+          iso_year, week_one_start = *iso_year_and_week_one_start(wkst)
+          probe_date = week_one_start + (7*52)
+          if probe_date.iso_year(wkst) == iso_year
+            53
+          else
+            52
+          end
+        end
+
+        # return the iso week number of the receiver
+        # == parameter
+        # wkst:: an integer representing the day of the week on which weeks are deemed to start. This uses
+        # the ruby convention where 0 represents Sunday.
+        def iso_week_num(wkst)
+          iso_year_and_week_num(wkst)[1]
+        end
+
+        # return the iso year of the receiver
+        # == parameter
+        # wkst:: an integer representing the day of the week on which weeks are deemed to start. This uses
+        # the ruby convention where 0 represents Sunday.
+        def iso_year(wkst)
+          iso_year_and_week_num(wkst)[0]
+        end
+        
+        # return the first day of the iso year of the receiver
+        # == parameter
+        # wkst:: an integer representing the day of the week on which weeks are deemed to start. This uses
+        # the ruby convention where 0 represents Sunday.
+        def iso_year_start(wkst)
+          iso_year_and_week_one_start(wkst)[1]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+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
+          RiCal::PropertyValue::DateTime.from_time(self)
+        end
+
+        alias_method :to_ri_cal_date_or_date_time_value, :to_ri_cal_date_time_value
+
+        # Return the natural ri_cal_property for this object
+        def to_ri_cal_property_value
+          to_ri_cal_date_time_value
+        end
+        
+        # Return a proxy to this object which will be interpreted as a floating time.
+        def with_floating_timezone
+          RiCal::TimeWithFloatingTimezone.new(self)
+        end
+      end
+    end
+  end
+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/core_extensions/time.rb

@@ -0,0 +1,11 @@
+require "#{File.dirname(__FILE__)}/time/conversions.rb"
+require "#{File.dirname(__FILE__)}/time/week_day_predicates.rb"
+require "#{File.dirname(__FILE__)}/time/calculations.rb"
+#- ©2009 Rick DeNatale
+#- All rights reserved. Refer to the file README.txt for the license
+#
+class Time #:nodoc:
+  include RiCal::CoreExtensions::Time::WeekDayPredicates
+  include RiCal::CoreExtensions::Time::Calculations  
+  include RiCal::CoreExtensions::DateTime::Conversions
+end

data/lib/ri_cal/core_extensions.rb

@@ -0,0 +1,6 @@
+#- ©2009 Rick DeNatale
+#- All rights reserved. Refer to the file README.txt for the license
+#
+Dir[File.dirname(__FILE__) + "/core_extensions/*.rb"].sort.each do |path|
+  require path
+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)
+      new("#{identifier.inspect} is not the identifier of a VTIMEZONE component of this calendar")
+    end
+    
+    def self.invalid_tzinfo_identifier(identifier)
+      new("#{identifier.inspect} is not known to the tzinfo database")
+    end
+  end
+end

data/lib/ri_cal/occurrence_enumerator.rb

@@ -0,0 +1,172 @@
+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)
+    end
+
+    def default_start_time # :nodoc:
+      dtstart && dtstart.to_ri_cal_date_time_value
+    end
+
+    class EmptyRulesEnumerator # :nodoc:
+      def self.next_occurrence
+        nil
+      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?}
+        self.nexts = @enumerators.map {|enumerator| enumerator.next_occurrence}
+      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[:start] < occurrence[:start])
+          @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[:start] == occurrence[:start]
+      end
+      
+      def exclude?(occurrence)
+        exclusion_match?(occurrence, exclusion_for(occurrence))
+      end
+      
+      # yield each occurrence to a block
+      # some components may be open-ended, e.g. have no COUNT or DTEND 
+      def each
+        occurrence = @rrules.next_occurrence
+        yielded = 0
+        @next_exclusion = @exrules.next_occurrence
+        while (occurrence)
+          if (@cutoff && occurrence[:start] >= @cutoff) || (@count && yielded >= @count)
+            occurrence = nil
+          else
+            unless exclude?(occurrence)
+              yielded += 1
+             yield @component.recurrence(occurrence)
+            end
+            occurrence = @rrules.next_occurrence
+          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
+    #
+    def set_occurrence_properties!(occurrence) # :nodoc:
+      occurrence_end = occurrence[:end]
+      occurrence_start = occurrence[:start]
+      @rrule_property = nil
+      @exrule_property = nil
+      @rdate_property = nil
+      @exdate_property = nil
+      @recurrence_id_property = occurrence_start
+      @dtstart_property = occurrence_start
+      if occurrence_end
+        @dtend_property = occurrence_end
+      else
+        if dtend
+          my_duration = @dtend_property - @dtstart_property
+          @dtend_property = occurrence_start + my_duration
+        end
+      end
+      self      
+    end
+    
+    def recurrence(occurrence) # :nodoc:
+      result = self.dup.set_occurrence_properties!(occurrence)
+    end
+  end
+end

data/lib/ri_cal/parser.rb

@@ -0,0 +1,138 @@
+module RiCal
+  #- ©2009 Rick DeNatale
+  #- All rights reserved. Refer to the file README.txt for the license
+  #
+  class Parser # :nodoc:
+    def next_line #:nodoc:
+      result = nil
+      begin
+        result = buffer_or_line
+        @buffer = nil
+        while /^\s/ =~ buffer_or_line
+          result = "#{result}#{@buffer[1..-1]}"
+          @buffer = nil
+        end
+      rescue EOFError
+        return nil
+      ensure
+        return result
+      end
+    end
+
+    def parse_params(string) #:nodoc:
+      if string
+        string.split(";").inject({}) { |result, val|
+          m = /^(.+)=(.+)$/.match(val)
+          invalid unless m
+          result[m[1]] = m[2]
+          result 
+        }
+      else
+        nil
+      end
+    end
+
+    def params_and_value(string) #:nodoc:
+      string = string.sub(/^:/,'')
+      return ["", string] unless string.match(/^;/)
+      segments = string.sub(';','').split(":")
+      return ["", string] if segments.length < 2
+      quote_count = 0
+      gathering_params = true
+      params = []
+      values = []
+      segments.each do |segment|
+        if gathering_params
+          params << segment
+          quote_count += segment.count("\"")
+          gathering_params = (1 == quote_count % 2)
+        else
+          values << segment
+        end
+      end
+      [params.join(":"), values.join(":")]
+    end
+
+    def separate_line(string) #:nodoc:
+      match = string.match(/^([^;:]*)(.*)$/)
+      name = match[1]
+      params, value = *params_and_value(match[2])
+      {
+        :name => name,
+        :params => parse_params(params),
+        :value => value
+      }
+    end
+
+    def next_separated_line #:nodoc:
+      line = next_line
+      line ? separate_line(line) : nil
+    end
+
+    def buffer_or_line #:nodoc:
+      @buffer ||= @io.readline.chomp
+    end
+
+    def initialize(io = StringIO.new("")) #:nodoc:
+      @io = io
+    end
+
+    def self.parse(io = StringIO.new("")) #:nodoc:
+      new(io).parse
+    end
+
+    def invalid #:nodoc:
+      raise Exception.new("Invalid icalendar file")
+    end
+
+    def still_in(component, separated_line) #:nodoc:
+      invalid unless separated_line
+      separated_line[:value] != component || separated_line[:name] != "END"
+    end
+
+    def parse #:nodoc:
+      result = []
+      while start_line = next_line
+        @parent_stack = []
+        result << parse_one(start_line, nil)
+      end
+      result
+    end
+
+    # TODO: Need to parse non-standard component types (iana-token or x-name)
+    def parse_one(start, parent_component) #:nodoc:
+
+      @parent_stack << parent_component
+      if Hash === start
+        first_line = start
+      else
+        first_line = separate_line(start)
+      end
+      invalid unless first_line[:name] == "BEGIN"
+      result = case first_line[:value]
+      when "VCALENDAR"
+        RiCal::Component::Calendar.from_parser(self, parent_component)
+      when "VEVENT"
+        RiCal::Component::Event.from_parser(self, parent_component)
+      when "VTODO"
+        RiCal::Component::Todo.from_parser(self, parent_component)
+      when "VJOURNAL"
+        RiCal::Component::Journal.from_parser(self, parent_component)
+      when "VFREEBUSY"
+        RiCal::Component::Freebusy.from_parser(self, parent_component)
+      when "VTIMEZONE"
+        RiCal::Component::Timezone.from_parser(self, parent_component)
+      when "VALARM"
+        RiCal::Component::Alarm.from_parser(self, parent_component)
+      when "DAYLIGHT"
+        RiCal::Component::Timezone::DaylightPeriod.from_parser(self, parent_component)
+      when "STANDARD"
+        RiCal::Component::Timezone::StandardPeriod.from_parser(self, parent_component)
+      else
+        invalid
+      end
+      @parent_stack.pop
+      result
+    end
+  end
+end