ri_cal 0.5.0

data/lib/ri_cal/component/event.rb

@@ -0,0 +1,60 @@
+require File.join(File.dirname(__FILE__), %w[.. properties event.rb])
+
+module RiCal
+  class Component
+    #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+    #
+    # An Event (VEVENT) calendar component groups properties describing a scheduled event.
+    # Events may have multiple occurrences
+    #
+    # Events may also contain one or more ALARM subcomponents
+    #
+    # to see the property accessing methods for this class see the RiCal::Properties::Event module
+    # to see the methods for enumerating occurrences of recurring events see the RiCal::OccurrenceEnumerator module
+    class Event < Component
+      include OccurrenceEnumerator
+
+      include RiCal::Properties::Event
+
+      def subcomponent_class #:nodoc:
+        {:alarm => Alarm }
+      end
+
+      def self.entity_name #:nodoc:
+        "VEVENT"
+      end
+      
+      # Return a date_time representing the time at which the event starts
+      def start_time
+        dtstart_property ? dtstart.to_datetime : nil
+      end
+      
+      # Return a date_time representing the time at which the event starts
+      def finish_property
+        if dtend_property
+          dtend_property
+        elsif duration_property
+          (dtstart_property + duration_property)
+        else
+          dtstart_property
+        end
+      end
+
+      # Return a date_time representing the time at which the event starts
+      def finish_time
+        prop = finish_property
+        prop ? prop.to_finish_time : nil
+      end
+      
+      def zulu_occurrence_range_start_time
+        dtstart_property ? dtstart_property.to_zulu_occurrence_range_start_time : nil
+       end
+      
+      def zulu_occurrence_range_finish_time
+        prop = finish_property
+        prop ? prop.to_zulu_occurrence_range_finish_time : nil
+      end
+      
+    end
+  end
+end

data/lib/ri_cal/component/freebusy.rb

@@ -0,0 +1,18 @@
+require File.join(File.dirname(__FILE__), %w[.. properties freebusy.rb])
+
+module RiCal
+  class Component
+    #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+    #
+    #  A Freebusy (VFREEBUSY) calendar component groups properties describing either a request for free/busy time,
+    #  a response to a request for free/busy time, or a published set of busy time.
+    # to see the property accessing methods for this class see the RiCal::Properties::Freebusy module
+    class Freebusy < Component
+      include RiCal::Properties::Freebusy        
+
+      def self.entity_name #:nodoc:
+        "VFREEBUSY"
+      end
+    end 
+  end
+end

data/lib/ri_cal/component/journal.rb

@@ -0,0 +1,30 @@
+
+require File.join(File.dirname(__FILE__), %w[.. properties journal.rb])
+
+module RiCal
+  class Component
+    #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+    #
+    #  A Journal (VJOURNAL) calendar component groups properties describing a journal entry.
+    #  Journals may have multiple occurrences
+    # to see the property accessing methods for this class see the RiCal::Properties::Journal module
+    # to see the methods for enumerating occurrences of recurring journals see the RiCal::OccurrenceEnumerator module
+    class Journal < Component
+      include RiCal::Properties::Journal
+      include RiCal::OccurrenceEnumerator
+
+      def self.entity_name #:nodoc:
+        "VJOURNAL"
+      end
+      
+      # Return a date_time representing the time at which the event starts
+      def start_time
+        dtstart.to_datetime
+      end
+      
+      # Journals take up no calendar time, so the finish time is always the same as the start_time
+      alias_method :finish_time, :start_time
+      
+    end
+  end
+end

data/lib/ri_cal/component/t_z_info_timezone.rb

@@ -0,0 +1,123 @@
+#- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+#
+# A wrapper class for a Timezone implemented by the TZInfo Gem
+# (or by Rails)
+class RiCal::Component::TZInfoTimezone < RiCal::Component::Timezone
+
+  class Period #:nodoc: all
+
+    def initialize(which, this_period, prev_period)
+      @which = which
+      @onset = this_period.local_start.strftime("%Y%m%dT%H%M%S")
+      @offset_from = format_rfc2445_offset(prev_period.utc_total_offset)
+      @offset_to = format_rfc2445_offset(this_period.utc_total_offset)
+      @abbreviation = this_period.abbreviation
+      @rdates = []
+    end
+
+    def add_period(this_period)
+      @rdates << this_period.local_start.strftime("%Y%m%dT%H%M%S")
+    end
+
+
+    def format_rfc2445_offset(seconds) #:nodoc:
+      abs_seconds = seconds.abs
+      h = (abs_seconds/3600).floor
+      m = (abs_seconds - (h * 3600))/60
+      h *= -1 if seconds < 0
+      sprintf("%+03d%02d", h, m)
+    end
+
+    def export_to(export_stream)
+      export_stream.puts "BEGIN:#{@which}"
+      export_stream.puts "DTSTART:#{@onset}"
+      export_stream.puts "RDATE:#{@rdates.join(",")}"
+      export_stream.puts "TZOFFSETFROM:#{@offset_from}"
+      export_stream.puts "TZOFFSETTO:#{@offset_to}"
+      export_stream.puts "TZNAME:#{@abbreviation}"
+      export_stream.puts "END:#{@which}"
+    end
+  end
+
+  class Periods #:nodoc: all
+
+    def initialize
+      @dst_period = @std_period = @previous_period = nil
+    end
+
+    def daylight_period(this_period, previous_period)
+      @daylight_period ||= Period.new("DAYLIGHT", this_period, previous_period)
+    end
+
+    def standard_period(this_period, previous_period)
+      @standard_period ||= Period.new("STANDARD", this_period, previous_period)
+    end
+
+    def log_period(period)
+      @periods ||= []
+      @periods << period unless @periods.include?(period)
+    end
+
+    def add_period(this_period)
+      if @previous_period
+        if this_period.dst?
+          period = daylight_period(this_period, @previous_period)
+        else
+          period = standard_period(this_period, @previous_period)
+        end
+        period.add_period(this_period)
+        log_period(period)
+      end
+      @previous_period = this_period
+    end
+
+    def export_to(export_stream)
+      @periods.each {|period| period.export_to(export_stream)}
+    end
+  end
+
+  attr_reader :tzinfo_timezone #:nodoc:
+
+  def initialize(tzinfo_timezone) #:nodoc:
+    @tzinfo_timezone = tzinfo_timezone
+  end
+
+  # convert time from this time zone to utc time
+  def local_to_utc(time)
+    @tzinfo_timezone.local_to_utc(time.to_ri_cal_ruby_value)
+  end
+
+  # convert time from utc time to this time zone
+  def utc_to_local(time)
+    @tzinfo_timezone.utc_to_local(time.to_ri_cal_ruby_value)
+  end
+
+  # return the time zone identifier
+  def identifier
+    @tzinfo_timezone.identifier
+  end
+
+  def export_local_to(export_stream, local_start, local_end) #:nodoc:
+    export_utc_to(export_stream, local_to_utc(local_start.to_ri_cal_ruby_value), local_to_utc(local_end.to_ri_cal_ruby_value))
+  end
+
+  def to_rfc2445_string(utc_start, utc_end) #:nodoc:
+    export_stream = StringIO.new
+    export_utc_to(export_stream, utc_start, utc_end)
+    export_stream.string
+  end
+
+  def export_utc_to(export_stream, utc_start, utc_end) #:nodoc:
+    export_stream.puts "BEGIN:VTIMEZONE","TZID;X-RICAL-TZSOURCE=TZINFO:#{identifier}"
+    periods = Periods.new
+    period = tzinfo_timezone.period_for_utc(utc_start)
+     #start with the period before the one containing utc_start
+    period = tzinfo_timezone.period_for_utc(period.utc_start - 1)
+    while period && period.utc_start < utc_end
+      periods.add_period(period)
+      period = tzinfo_timezone.period_for_utc(period.utc_end + 1)
+    end
+    periods.export_to(export_stream)
+    export_stream.puts "END:VTIMEZONE\n"
+  end
+end

data/lib/ri_cal/component/timezone.rb

@@ -0,0 +1,196 @@
+require File.join(File.dirname(__FILE__), %w[.. properties timezone.rb])
+
+module RiCal
+  class Component
+    #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+    #
+    # An Timezone (VTIMEZONE) calendar component describes a timezone used within the calendar.
+    # A Timezone has two or more TimezonePeriod subcomponents which describe the transitions between
+    # standard and daylight saving time.
+    #
+    # to see the property accessing methods for this class see the RiCal::Properties::Timezone module
+    class Timezone < Component
+      include RiCal::Properties::Timezone
+
+        # The identifier of the timezone, e.g. "Europe/Paris".
+        def identifier
+          tzid
+        end
+
+        # An alias for identifier.
+        def name
+          # Don't use alias, as identifier gets overridden.
+          identifier
+        end
+        
+        def rational_utc_offset(local) #:nodoc:
+          Rational(period_for_local(local, true).utc_total_offset, 3600) / 24
+        end
+
+        # Returns the TimezonePeriod for the given UTC time. utc can either be a DateTime,
+        # Time or integer timestamp (Time.to_i). Any timezone information in utc is ignored (it is treated as a UTC time).
+        def period_for_utc(time)
+          last_period(last_before_utc(standard, time), last_before_utc(daylight, time))
+        end
+
+        # Returns the set of TimezonePeriod instances that are valid for the given
+        # local time as an array. If you just want a single period, use
+        # period_for_local instead and specify how ambiguities should be resolved.
+        # Returns an empty array if no periods are found for the given time.
+        def periods_for_local(local)
+          local = local.to_ri_cal_date_time_value
+          candidate_standard = last_before_local(standard, local)
+          candidate_daylight = last_before_local(daylight, local)
+          if candidate_daylight && candidate_daylight.swallows_local?(local, candidate_standard)
+            []  # Invalid local time
+          elsif candidate_standard
+            if candidate_daylight
+              if candidate_daylight.dtstart > candidate_standard.dtstart
+                [candidate_daylight]
+              elsif candidate_standard.ambiguous_local?(local)
+                [candidate_daylight, candidate_standard]
+              else
+                [candidate_standard].compact
+              end
+            else
+              [candidate_standard].compact
+            end
+          end
+        end
+
+
+        # Returns the TimezonePeriod for the given local time. local can either be
+        # a DateTime, Time or integer timestamp (Time.to_i). Any timezone
+        # information in local is ignored (it is treated as a time in the current
+        # timezone).
+        #
+        # Warning: There are local times that have no equivalent UTC times (e.g.
+        # in the transition from standard time to daylight savings time). There are
+        # also local times that have more than one UTC equivalent (e.g. in the
+        # transition from daylight savings time to standard time).
+        #
+        # In the first case (no equivalent UTC time), a PeriodNotFound exception
+        # will be raised.
+        #
+        # In the second case (more than one equivalent UTC time), an AmbiguousTime
+        # exception will be raised unless the optional dst parameter or block
+        # handles the ambiguity.
+        #
+        # If the ambiguity is due to a transition from daylight savings time to
+        # standard time, the dst parameter can be used to select whether the
+        # daylight savings time or local time is used. For example,
+        #
+        #   Timezone.get('America/New_York').period_for_local(DateTime.new(2004,10,31,1,30,0))
+        #
+        # would raise an AmbiguousTime exception.
+        #
+        # Specifying dst=true would the daylight savings period from April to
+        # October 2004. Specifying dst=false would return the standard period
+        # from October 2004 to April 2005.
+        #
+        # If the dst parameter does not resolve the ambiguity, and a block is
+        # specified, it is called. The block must take a single parameter - an
+        # array of the periods that need to be resolved. The block can select and
+        # return a single period or return nil or an empty array
+        # to cause an AmbiguousTime exception to be raised.
+        #
+        # TODO: need to check for ambiguity
+        def period_for_local(local, dst=nil)
+          results = periods_for_local(local)
+
+          if results.empty?
+            raise TZInfo::PeriodNotFound
+          elsif results.size < 2
+            results.first
+          else
+            # ambiguous result try to resolve
+
+            unless dst.nil?
+              matches = results.find_all {|period| period.dst? == dst}
+              results = matches unless matches.empty?
+            end
+
+            if results.size < 2
+              results.first
+            else
+              # still ambiguous, try the block
+
+              if block_given?
+                results = yield results
+              end
+
+              if results.is_a?(TimezonePeriod)
+                results
+              elsif results && results.size == 1
+                results.first
+              else
+                raise TZInfo::AmbiguousTime, "#{local} is an ambiguous local time."
+              end
+            end
+          end
+        end
+
+        # convert time from utc time to this time zone
+        def utc_to_local(time)
+          time = time.to_ri_cal_date_time_value
+          converted = time + period_for_utc(time).tzoffsetto_property
+          converted.tzid = identifier
+          converted
+        end
+
+        # convert time from this time zone to utc time
+        def local_to_utc(time)
+          time = time.to_ri_cal_date_time_value
+          period = period_for_local(time)
+          converted = time - period.tzoffsetto_property
+          converted.tzid = "UTC"
+          converted
+        end
+      end
+
+      def self.entity_name #:nodoc:
+        "VTIMEZONE"
+      end
+
+      def standard #:nodoc:
+        @subcomponents["STANDARD"]
+      end
+
+      def daylight #:nodoc:
+        @subcomponents["DAYLIGHT"]
+      end
+
+      def last_period(standard, daylight) #:nodoc:
+        if standard
+          if daylight
+            standard.dtstart > daylight.dtstart ? standard : daylight
+          else
+            standard
+          end
+        else
+          daylight
+        end
+      end
+
+      def last_before_utc(period_array, time) #:nodoc:
+        candidates = period_array.map {|period|
+          period.last_before_utc(time)
+        }
+        result = candidates.max {|a, b| a.dtstart_property <=> b.dtstart_property}
+        result
+      end
+
+      def last_before_local(period_array, time) #:nodoc:
+        candidates = period_array.map {|period|
+          period.last_before_local(time)
+        }
+        result = candidates.max {|a, b| a.dtstart_property <=> b.dtstart_property}
+        result
+      end
+  end
+end
+
+
+%w[timezone_period.rb daylight_period.rb standard_period.rb].each do |filename|
+  require "#{File.dirname(__FILE__)}/timezone/#{filename}"
+end

data/lib/ri_cal/component/timezone/daylight_period.rb

@@ -0,0 +1,25 @@
+module RiCal
+  class Component
+    class Timezone
+      #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+      #
+      # A DaylightPeriod is a TimezonePeriod during which daylight saving time *is* in effect
+      class DaylightPeriod < TimezonePeriod #:nodoc: all
+
+        def self.entity_name #:nodoc:
+          "DAYLIGHT"
+        end
+
+        def dst?
+          true
+        end
+
+        def swallows_local?(local, std_candidate)
+          ([local.year, local.month, local.day] == [dtstart.year,dtstart.month, dtstart.day]) && 
+             local >= dtstart_property &&
+             local.advance(:seconds => (std_candidate.utc_total_offset - utc_total_offset)) < dtstart_property
+        end
+      end
+    end
+  end
+end