demingfactor-ri_cal 0.9.0

data/docs/incrementers.txt

@@ -0,0 +1,7 @@
+Seconds - Freq="SECONDLY", BYSECOND
+Minutes - Freq="MINUTELY", BYMINUTE
+Hours -   Freq="HOURLY",   BYHOUR
+Days -    Freq="DAILY",    BYDAY, BYMONTHDAY, BYYEARDAY
+Weeks -   Freq="WEEKLY",   BYWEEKNO
+Months -  Freq="MONTHLY",  BYMONTH
+Years -   Freq="YEARLY"

data/lib/ri_cal/component/alarm.rb

@@ -0,0 +1,19 @@
+module RiCal
+
+  class Component
+    #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+    #
+    # An Alarm component groups properties defining a reminder or alarm associated with an event or to-do
+    # TODO: The Alarm component has complex cardinality restrictions depending on the value of the action property
+    # i.e. audio, display, email, and proc alarms, this is currently not checked or enforced
+    #
+    # to see the property accessing methods for this class see the RiCal::Properties::Alarm module
+    class Alarm < Component
+      include RiCal::Properties::Alarm
+
+      def self.entity_name #:nodoc:
+        "VALARM"
+      end
+    end
+  end
+end

data/lib/ri_cal/component/calendar.rb

@@ -0,0 +1,257 @@
+module RiCal
+  class Component
+    #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+    #
+    # to see the property accessing methods for this class see the RiCal::Properties::Calendar module
+    class Calendar < Component
+      include RiCal::Properties::Calendar
+      attr_reader :tz_source #:nodoc:
+
+      def initialize(parent=nil,entity_name = nil, &init_block) #:nodoc:
+        @tz_source = 'TZINFO' # Until otherwise told
+        super
+      end
+
+      def self.entity_name #:nodoc:
+        "VCALENDAR"
+      end
+
+      def tz_info_source? #:nodoc:
+        @tz_source == 'TZINFO'
+      end
+
+      def required_timezones # :nodoc:
+        @required_timezones ||=  RequiredTimezones.new
+      end
+
+      def subcomponent_class # :nodoc:
+        {
+          :event => Event,
+          :todo  => Todo,
+          :journal => Journal,
+          :freebusy => Freebusy,
+          :timezone => Timezone,
+        }
+      end
+
+      def export_properties_to(export_stream) # :nodoc:
+        prodid_property.params["X-RICAL-TZSOURCE"] = @tz_source if @tz_source
+        export_prop_to(export_stream, "PRODID", prodid_property)
+        export_prop_to(export_stream, "CALSCALE", calscale_property)
+        export_prop_to(export_stream, "VERSION", version_property)
+        export_prop_to(export_stream, "METHOD", method_property)
+      end
+
+      def prodid_property_from_string(line) # :nodoc:
+        result = super
+        @tz_source = prodid_property.params["X-RICAL-TZSOURCE"]
+        result
+      end
+
+      # Return the default time zone identifier for this calendar
+      def default_tzid
+        @default_tzid || PropertyValue::DateTime.default_tzid
+      end
+
+      # Set the default time zone identifier for this calendar
+      # To set the default to floating times use a value of :floating
+      def default_tzid=(value)
+        @default_tzid=value
+      end
+
+      # return an array of event components contained within this Calendar
+      def events
+        subcomponents["VEVENT"]
+      end
+
+      # add an event to the calendar
+      def add_subcomponent(component)
+        super(component)
+        component.add_date_times_to(required_timezones) if tz_info_source?
+      end
+
+      # return an array of todo components contained within this Calendar
+      def todos
+        subcomponents["VTODO"]
+      end
+
+      # return an array of journal components contained within this Calendar
+      def journals
+        subcomponents["VJOURNAL"]
+      end
+
+      # return an array of freebusy components contained within this Calendar
+      def freebusys
+        subcomponents["VFREEBUSY"]
+      end
+
+      class TimezoneID #:nodoc:
+        attr_reader :identifier, :calendar
+        def initialize(identifier, calendar)
+          self.identifier, self.calendar = identifier, calendar
+        end
+
+        def tzinfo_timezone
+          nil
+        end
+
+        def resolved
+          calendar.find_timezone(identifier)
+        end
+
+        def local_to_utc(local)
+          resolved.local_to_utc(date_time_prop)
+        end
+      end
+
+      # return an array of timezone components contained within this calendar
+      def timezones
+        subcomponents["VTIMEZONE"]
+      end
+
+      class TZInfoWrapper #:nodoc:
+        attr_reader :tzinfo, :calendar #:nodoc:
+        def initialize(tzinfo, calendar) #:nodoc:
+          @tzinfo = tzinfo
+          @calendar = calendar
+        end
+
+        def identifier #:nodoc:
+          tzinfo.identifier
+        end
+
+        def local_date_time(ruby_time, tzid) #:nodoc:
+          RiCal::PropertyValue::DateTime.new(calendar, :value => ruby_time.strftime("%Y%m%dT%H%M%S"), :params => {'TZID' => tzid})
+        end
+
+        def utc_date_time(ruby_time) #:nodoc
+            RiCal::PropertyValue::DateTime.new(calendar, :value => ruby_time.strftime("%Y%m%dT%H%M%SZ"))
+        end
+
+        def local_to_utc(utc) #:nodoc:
+          utc_date_time(tzinfo.local_to_utc(utc.to_ri_cal_ruby_value))
+        end
+
+        def utc_to_local(local) #:nodoc:
+          local_date_time(tzinfo.utc_to_local(local.to_ri_cal_ruby_value), tzinfo.identifier)
+        end
+
+
+        def rational_utc_offset(local)
+          RiCal.RationalOffset[tzinfo.period_for_local(local, true).utc_total_offset]
+        end
+
+      end
+
+      def find_timezone(identifier)  #:nodoc:
+        if tz_info_source?
+          begin
+            TZInfoWrapper.new(TZInfo::Timezone.get(identifier), self)
+          rescue ::TZInfo::InvalidTimezoneIdentifier => ex
+            raise RiCal::InvalidTimezoneIdentifier.invalid_tzinfo_identifier(identifier)
+          end
+        else
+          result = timezones.find {|tz| tz.tzid == identifier}
+          raise RiCal::InvalidTimezoneIdentifier.not_found_in_calendar(identifier) unless result
+          result
+        end
+      end
+
+      def export_required_timezones(export_stream) # :nodoc:
+        required_timezones.export_to(export_stream)
+      end
+
+      class FoldingStream #:nodoc:
+        attr_reader :stream #:nodoc:
+        def initialize(stream) #:nodoc:
+          @stream = stream || StringIO.new
+        end
+
+        def string #:nodoc:
+          stream.string
+        end
+
+        if RUBY_VERSION =~ /^1\.9/
+          def utf8_safe_split(string, n)
+            if string.bytesize <= n
+              [string, nil]
+            else
+              bytes = string.bytes.to_a
+              while (128..191).include?(bytes[n])
+                n = n - 1
+              end
+              before = bytes[0,n]
+              after = bytes[n..-1]
+              [before.pack("C*").force_encoding("utf-8"), after.empty? ? nil : after.pack("C*").force_encoding("utf-8")]
+            end
+          end
+        else
+          def valid_utf8?(string)
+            string.unpack("U") rescue nil
+          end
+
+          def utf8_safe_split(string, n)
+            if string.length <= n
+              [string, nil]
+            else
+              before = string[0, n]
+              after = string[n..-1]
+              until valid_utf8?(after)
+                n = n - 1
+                before = string[0, n]
+                after = string[n..-1]
+              end      
+              [before, after.empty? ? nil : after]
+            end
+          end
+        end
+
+        def fold(string) #:nodoc:
+          line, remainder = *utf8_safe_split(string, 73)
+          stream.puts(line)
+          while remainder
+            line, remainder = *utf8_safe_split(remainder, 72)
+            stream.puts(" #{line}")
+          end
+        end
+
+        def puts(*strings) #:nodoc:
+          strings.each do |string|
+            string.split("\n").each do |line|
+              fold(line)
+            end
+          end
+        end
+      end
+
+      # Export this calendar as an iCalendar file.
+      # if to is nil (the default) then this method will return a string,
+      # otherwise to should be an IO to which the iCalendar file contents will be written
+      def export(to=nil)
+        export_stream = FoldingStream.new(to)
+        export_stream.puts("BEGIN:VCALENDAR")
+        export_properties_to(export_stream)
+        export_x_properties_to(export_stream)
+        export_required_timezones(export_stream)
+        export_subcomponent_to(export_stream, events)
+        export_subcomponent_to(export_stream, todos)
+        export_subcomponent_to(export_stream, journals)
+        export_subcomponent_to(export_stream, freebusys)
+        subcomponents.each do |key, value|
+          unless %{VEVENT VTODO VJOURNAL VFREEBUSYS}.include?(key)
+            export_subcomponent_to(export_stream, value)
+          end
+        end
+        export_stream.puts("END:VCALENDAR")
+        if to
+          nil
+        else
+          export_stream.string
+        end
+      end
+      
+      alias_method :export_to, :export
+
+    end
+  end
+end

data/lib/ri_cal/component/event.rb

@@ -0,0 +1,58 @@
+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_property representing the time at which the event ends
+      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,16 @@
+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,27 @@
+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/non_standard.rb

@@ -0,0 +1,33 @@
+module RiCal
+
+  class Component
+    #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+    #
+    # An NonStandard component represents a component (or subcomponent) not listed in RFC2445.
+    # For example some icalendar data contains VVENUE components, a proposed extension to RFC2445
+    # which was dropped.
+    class NonStandard < Component
+      attr_reader :entity_name
+      
+      def initialize(parent, entity_name)
+        super(parent)
+        @entity_name = entity_name
+        @source_lines = []
+      end
+      
+      def process_line(parser, line) #:nodoc:
+        if line[:name] == "BEGIN"
+          parse_subcomponent(parser, line)
+        else
+          @source_lines << parser.last_line_str
+        end
+      end
+      
+      def export_properties_to(stream)
+        @source_lines.each do |line|
+          stream.puts(line)
+        end
+      end
+    end
+  end
+end

data/lib/ri_cal/component/t_z_info_timezone.rb

@@ -0,0 +1,153 @@
+#- ©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
+      if prev_period
+        @onset = period_local_end(prev_period)
+        @offset_from = format_rfc2445_offset(prev_period.utc_total_offset)
+      else
+        @onset = period_local_start(this_period)
+        @offset_from = format_rfc2445_offset(this_period.utc_total_offset)
+      end
+      @offset_to = format_rfc2445_offset(this_period.utc_total_offset)
+      @abbreviation = this_period.abbreviation
+      @rdates = []
+    end
+    
+    def daylight?
+      @which == "DAYLIGHT"
+    end
+    
+    def period_local_end(period)
+      (period.local_end || DateTime.parse("99990101T000000")).strftime("%Y%m%dT%H%M%S")
+    end
+    
+    # This assumes a 1 hour shift which is why we use the previous period local end when
+    # possible
+    def period_local_start(period)
+      shift = daylight? ? Rational(-1, 24) : Rational(1, 24)
+      ((period.local_start || DateTime.parse("16010101T000000")) + shift).strftime("%Y%m%dT%H%M%S")
+    end
+
+    def add_period(this_period)
+      @rdates << period_local_start(this_period)
+    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}"
+      @rdates.each do |rdate|
+        export_stream.puts "RDATE:#{rdate}"
+      end
+      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 empty?
+      @periods.nil? || @periods.empty?
+    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, force=false)
+      if @previous_period || force
+        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 = initial_period = tzinfo_timezone.period_for_utc(utc_start)
+     #start with the period before the one containing utc_start
+    prev_period = period.utc_start && tzinfo_timezone.period_for_utc(period.utc_start - 1)
+    period = prev_period if prev_period
+    while period && period.utc_start && period.utc_start < utc_end
+      periods.add_period(period)
+      period = period.utc_end && tzinfo_timezone.period_for_utc(period.utc_end + 1)
+    end
+    periods.add_period(initial_period, :force) if periods.empty?
+    periods.export_to(export_stream)
+    export_stream.puts "END:VTIMEZONE\n"
+  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