awallis-ri_cal 0.8.8

data/lib/ri_cal/component/timezone.rb

@@ -0,0 +1,197 @@
+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
+      
+      autoload :TimezonePeriod, "ri_cal/component/timezone/timezone_period.rb"
+      autoload :StandardPeriod, "ri_cal/component/timezone/standard_period.rb"
+      autoload :DaylightPeriod, "ri_cal/component/timezone/daylight_period.rb"
+      
+      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:
+          # 86400 is the number of seconds in a day
+          RiCal.RationalOffset[period_for_local(local, true).utc_total_offset]
+        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
+
+

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

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

@@ -0,0 +1,23 @@
+module RiCal
+  class Component
+    class Timezone
+      #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+      #
+      # A StandardPeriod is a TimezonePeriod during which daylight saving time is *not* in effect
+      class StandardPeriod < TimezonePeriod #:nodoc: all
+
+        def self.entity_name #:nodoc:
+          "STANDARD"
+        end
+        
+        def dst?
+          false
+        end
+        
+        def ambiguous_local?(time)
+          [time.year, time.month, time.day] == [dtstart.year, dtstart.month, dtstart.day]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+module RiCal
+  class Component
+    class Timezone
+      #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+      #
+      # A TimezonePeriod is a component of a timezone representing a period during which a particular offset from UTC is
+      # in effect.
+      #
+      # to see the property accessing methods for this class see the RiCal::Properties::TimezonePeriod module
+      class TimezonePeriod < Component
+        include Properties::TimezonePeriod
+
+        include OccurrenceEnumerator
+
+        def occurrence_cache #:nodoc:
+          @occurrence_cache ||= []
+        end
+
+        def zone_identifier #:nodoc:
+          tzname.first
+        end
+
+        def dtend #:nodoc:
+          nil
+        end
+
+        def exdate_property #:nodoc:
+          nil
+        end
+
+        def utc_total_offset #:nodoc:
+          tzoffsetto_property.to_seconds
+        end
+
+        def exrule_property #:nodoc:
+          nil
+        end
+
+        def last_before_utc(utc_time) #:nodoc:
+          last_before_local(utc_time + tzoffsetfrom_property)
+        end
+
+        def fill_cache(local_time)
+          if occurrence_cache.empty? || occurrence_cache.last.dtstart_property <= local_time
+            while true
+              occurrence = enumeration_instance.next_occurrence
+              break unless occurrence
+              occurrence = recurrence(occurrence)
+              occurrence_cache << occurrence
+              break if occurrence.dtstart_property > local_time
+            end
+          end
+        end
+
+        def last_before_local(local_time) #:nodoc:
+          if recurs?
+            fill_cache(local_time)
+            cand_occurrence = nil
+            occurrence_cache.each do |occurrence|
+              return cand_occurrence if occurrence.dtstart_property > local_time
+              cand_occurrence = occurrence
+            end
+            return cand_occurrence
+          else
+            return self
+          end
+        end
+
+         def enumeration_instance
+          @enumeration_instance ||= super
+        end
+      end
+    end
+  end
+end
+

data/lib/ri_cal/component/todo.rb

@@ -0,0 +1,42 @@
+module RiCal
+  class Component
+    #- ©2009 Rick DeNatale
+    #- All rights reserved. Refer to the file README.txt for the license
+    #
+    # A Todo (VTODO) calendar component groups properties describing a to-do
+    # Todos may have multiple occurrences
+    #
+    # Todos may also contain one or more ALARM subcomponents
+    # to see the property accessing methods for this class see the RiCal::Properties::Todo module
+    # to see the methods for enumerating occurrences of recurring to-dos see the RiCal::OccurrenceEnumerator module
+    class Todo < Component
+      include Properties::Todo
+      include OccurrenceEnumerator
+
+      def self.entity_name #:nodoc:
+        "VTODO"
+      end
+
+      def subcomponent_class #:nodoc:
+        {:alarm => Alarm }
+      end
+      
+      # Return a date_time representing the time at which the todo should start
+      def start_time
+        dtstart_property ? dtstart.to_datetime : nil
+      end
+      
+      # Return a date_time representing the time at which the todo is due
+      def finish_time
+        if due
+          due_property.to_finish_time
+        elsif duration_property && dtstart_property
+          (dtstart_property + duration_property).to_finish_time
+        else
+          nil
+        end
+      end
+      
+    end
+  end
+end

data/lib/ri_cal/core_extensions.rb

@@ -0,0 +1,11 @@
+#- ©2009 Rick DeNatale
+#- All rights reserved. Refer to the file README.txt for the license
+#
+
+require "ri_cal/core_extensions/array.rb"
+require "ri_cal/core_extensions/date.rb"
+require "ri_cal/core_extensions/date_time.rb"
+require "ri_cal/core_extensions/object.rb"
+require "ri_cal/core_extensions/string.rb"
+require "ri_cal/core_extensions/time.rb"
+

data/lib/ri_cal/core_extensions/array.rb

@@ -0,0 +1,7 @@
+require "ri_cal/core_extensions/array/conversions.rb"
+class Array #:nodoc:
+  #- ©2009 Rick DeNatale
+  #- All rights reserved. Refer to the file README.txt for the license
+  #
+  include RiCal::CoreExtensions::Array::Conversions
+end

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

@@ -0,0 +1,15 @@
+module RiCal
+  module CoreExtensions #:nodoc:
+    module Array #:nodoc:
+      #- ©2009 Rick DeNatale
+      #- All rights reserved. Refer to the file README.txt for the license
+      #
+      module Conversions
+        # return the concatenation of the elements representation in rfc 2445 format
+        def to_rfc2445_string # :doc:
+          join(",")
+        end
+      end
+    end
+  end
+end

data/lib/ri_cal/core_extensions/date.rb

@@ -0,0 +1,13 @@
+require "ri_cal/core_extensions/date/conversions.rb"
+require "ri_cal/core_extensions/time/week_day_predicates.rb"
+require "ri_cal/core_extensions/time/calculations.rb"
+require 'date'
+
+class Date #:nodoc:
+  #- ©2009 Rick DeNatale
+  #- All rights reserved. Refer to the file README.txt for the license
+  #
+  include RiCal::CoreExtensions::Time::WeekDayPredicates
+  include RiCal::CoreExtensions::Time::Calculations
+  include RiCal::CoreExtensions::Date::Conversions
+end

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

@@ -0,0 +1,56 @@
+module RiCal
+  module CoreExtensions #:nodoc:
+    module Date #:nodoc:
+      #- ©2009 Rick DeNatale
+      #- All rights reserved. Refer to the file README.txt for the license
+      #
+      module Conversions #:nodoc:
+        # Return an RiCal::PropertyValue::DateTime representing the receiver
+        def to_ri_cal_date_time_value(timezone_finder = nil)
+          RiCal::PropertyValue::DateTime.new(timezone_finder, :value => self)
+        end
+        
+        # Return an RiCal::PropertyValue::Date representing the receiver
+        def to_ri_cal_date_value(timezone_finder = nil)
+          RiCal::PropertyValue::Date.new(timezone_finder, :value => self)
+        end
+
+        alias_method :to_ri_cal_date_or_date_time_value, :to_ri_cal_date_value
+        alias_method :to_ri_cal_occurrence_list_value, :to_ri_cal_date_value
+        
+        # Return the natural ri_cal_property for this object
+        def to_ri_cal_property_value(timezone_finder = nil)
+          to_ri_cal_date_value(timezone_finder)
+        end
+        
+        def to_overlap_range_start
+          to_datetime
+        end
+        
+        def to_overlap_range_end
+          to_ri_cal_date_time_value.end_of_day.to_datetime
+        end
+        
+        unless Date.instance_methods.map {|selector| selector.to_sym}.include?(:to_date)
+          # A method to keep Time, Date and DateTime instances interchangeable on conversions.
+          # In this case, it simply returns +self+.
+          def to_date
+            self
+          end
+        end
+        unless Date.instance_methods.map {|selector| selector.to_sym}.include?(:to_datetime)
+          # Converts a Date instance to a DateTime, where the time is set to the beginning of the day
+          # and UTC offset is set to 0.
+          #
+          # ==== Examples
+          #   date = Date.new(2007, 11, 10)  # => Sat, 10 Nov 2007
+          #
+          #   date.to_datetime               # => Sat, 10 Nov 2007 00:00:00 0000
+          def to_datetime
+            ::DateTime.civil(year, month, day, 0, 0, 0, 0)
+          end
+        end
+      end
+    end
+  end
+end