demingfactor-ri_cal 0.9.0

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/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/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/component.rb

@@ -0,0 +1,256 @@
+module RiCal
+  #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+  #
+  class Component #:nodoc:
+
+    autoload :Alarm, "ri_cal/component/alarm.rb"
+    autoload :Calendar, "ri_cal/component/calendar.rb"
+    autoload :Event, "ri_cal/component/event.rb"
+    autoload :Freebusy, "ri_cal/component/freebusy.rb"
+    autoload :Journal, "ri_cal/component/journal.rb"
+    autoload :NonStandard, "ri_cal/component/non_standard.rb"
+    autoload :TZInfoTimezone, "ri_cal/component/t_z_info_timezone.rb"
+    autoload :Timezone, "ri_cal/component/timezone.rb"
+    autoload :Todo, "ri_cal/component/todo.rb"
+
+    class ComponentBuilder #:nodoc:
+      def initialize(component)
+        @component = component
+      end
+
+      def method_missing(selector, *args, &init_block) #:nodoc:
+        if(sub_comp_class = @component.subcomponent_class[selector])
+          if init_block
+            sub_comp = sub_comp_class.new(@component)
+            if init_block.arity == 1
+              yield ComponentBuilder.new(sub_comp)
+            else
+              ComponentBuilder.new(sub_comp).instance_eval(&init_block)
+            end
+            self.add_subcomponent(sub_comp)
+          end
+        else
+          sel = selector.to_s
+          sel = "#{sel}=" unless /(^(add_)|(remove_))|(=$)/ =~ sel
+          if @component.respond_to?(sel)
+            @component.send(sel, *args)
+          else
+            super
+          end
+        end
+      end
+    end
+
+    attr_accessor :imported #:nodoc:
+
+    def initialize(parent=nil, entity_name = nil, &init_block) #:nodoc:
+      @parent = parent
+      if block_given?
+        if init_block.arity == 1
+          init_block.call(ComponentBuilder.new(self))
+        else
+          ComponentBuilder.new(self).instance_eval(&init_block)
+        end
+      end
+    end
+
+    def default_tzid #:nodoc:
+      if @parent
+        @parent.default_tzid
+      else
+        PropertyValue::DateTime.default_tzid
+      end
+    end
+
+    def find_timezone(identifier) #:nodoc:
+      if @parent
+        @parent.find_timezone(identifier)
+      else
+        begin
+          Calendar::TZInfoWrapper.new(TZInfo::Timezone.get(identifier), self)
+        rescue ::TZInfo::InvalidTimezoneIdentifier => ex
+          raise RiCal::InvalidTimezoneIdentifier.invalid_tzinfo_identifier(identifier)
+        end
+      end
+    end
+
+    def tz_info_source?
+      if @parent
+        @parent.tz_info_source?
+      else
+        true
+      end
+    end
+
+    def time_zone_for(ruby_object) #:nodoc:
+      @parent.time_zone_for(ruby_object) #:nodoc:
+    end
+
+    def subcomponent_class #:nodoc:
+      {}
+    end
+
+    def self.from_parser(parser, parent, entity_name) #:nodoc:
+      entity = self.new(parent, entity_name)
+      entity.imported = true
+      line = parser.next_separated_line
+      while parser.still_in(entity_name, line)
+        entity.process_line(parser, line)
+        line = parser.next_separated_line
+      end
+      entity
+    end
+
+    def self.parse(io) #:nodoc:
+      Parser.new(io).parse
+    end
+
+    def imported? #:nodoc:
+      imported
+    end
+
+    def self.parse_string(string) #:nodoc:
+      parse(StringIO.new(string))
+    end
+
+    def subcomponents #:nodoc:
+      @subcomponents ||= Hash.new {|h, k| h[k] = []}
+    end
+
+    def entity_name #:nodoc:
+      self.class.entity_name
+    end
+
+    # return an array of Alarm components within this component :nodoc:
+    # Alarms may be contained within Events, and Todos
+    def alarms
+      subcomponents["VALARM"]
+    end
+
+    def add_subcomponent(component) #:nodoc:
+      subcomponents[component.entity_name] << component
+    end
+
+    def parse_subcomponent(parser, line) #:nodoc:
+      subcomponents[line[:value]] << parser.parse_one(line, self)
+    end
+
+    def process_line(parser, line) #:nodoc:
+      if line[:name] == "BEGIN"
+        parse_subcomponent(parser, line)
+      else
+        setter = self.class.property_parser[line[:name]]
+        if setter
+          send(setter, line)
+        else
+          self.add_x_property(line[:name], PropertyValue::Text.new(self, line))
+        end
+      end
+    end
+
+    # return a hash of any extended properties, (i.e. those with a property name starting with "X-"
+    # representing an extension to the RFC 2445 specification)
+    def x_properties
+      @x_properties ||= Hash.new {|h,k| h[k] = []}
+    end
+
+    # Add a n extended property
+    def add_x_property(name, prop, debug=false)
+      x_properties[name.gsub("_","-").upcase] << prop.to_ri_cal_text_property
+    end
+
+    def method_missing(selector, *args, &b) #:nodoc:
+      xprop_candidate = selector.to_s
+      if (match = /^(x_.+)(=?)$/.match(xprop_candidate))
+        x_property_key = match[1].gsub('_','-').upcase
+        if match[2] == "="
+          args.each do |val|
+            add_x_property(x_property_key, val)
+          end
+        else
+          x_properties[x_property_key].map {|property| property.value}
+        end
+      else
+        super
+      end
+    end
+
+    # Predicate to determine if the component is valid according to RFC 2445
+    def valid?
+      !mutual_exclusion_violation
+    end
+
+    def initialize_copy(original) #:nodoc:
+    end
+
+    def prop_string(prop_name, *properties) #:nodoc:
+      properties = properties.flatten.compact
+      if properties && !properties.empty?
+        properties.map {|prop| "#{prop_name}#{prop.to_s}"}.join("\n")
+      else
+        nil
+      end
+    end
+
+    def add_property_date_times_to(required_timezones, property) #:nodoc:
+      if property
+        if Array === property
+          property.each do |prop|
+            prop.add_date_times_to(required_timezones)
+          end
+        else
+          property.add_date_times_to(required_timezones)
+        end
+      end
+    end
+
+    def export_prop_to(export_stream, name, prop) #:nodoc:
+      if prop
+        string = prop_string(name, prop)
+        export_stream.puts(string) if string
+      end
+    end
+
+    def export_x_properties_to(export_stream) #:nodoc:
+      x_properties.each do |name, props|
+        props.each do | prop |
+          export_stream.puts("#{name}:#{prop}")
+        end
+      end
+    end
+
+    def export_subcomponent_to(export_stream, subcomponent) #:nodoc:
+      subcomponent.each do |component|
+        component.export_to(export_stream)
+      end
+    end
+
+    # return a string containing the rfc2445 format of the component
+    def to_s
+      io = StringIO.new
+      export_to(io)
+      io.string
+    end
+
+    # Export this component to an export stream
+    def export_to(export_stream)
+      export_stream.puts("BEGIN:#{entity_name}")
+      export_properties_to(export_stream)
+      export_x_properties_to(export_stream)
+      subcomponents.values.each do |sub|
+        export_subcomponent_to(export_stream, sub)
+      end
+      export_stream.puts("END:#{entity_name}")
+    end
+
+    # Export this single component as an iCalendar component containing only this component and
+    # any required additional components (i.e. VTIMEZONES referenced from this component)
+    # if stream is nil (the default) then this method will return a string,
+    # otherwise stream should be an IO to which the iCalendar file contents will be written
+    def export(stream=nil)
+      wrapper_calendar = Calendar.new
+      wrapper_calendar.add_subcomponent(self)
+      wrapper_calendar.export(stream)
+    end
+  end
+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/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/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

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