demingfactor-ri_cal 0.9.0

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

@@ -0,0 +1,50 @@
+require 'date'
+module RiCal
+  module CoreExtensions #:nodoc:
+    module DateTime #: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) #:nodoc:
+          RiCal::PropertyValue::DateTime.new(
+               timezone_finder, 
+               :value => strftime("%Y%m%dT%H%M%S"), 
+               :params => {"TZID" => self.tzid || :default})
+        end
+
+        alias_method :to_ri_cal_date_or_date_time_value, :to_ri_cal_date_time_value #:nodoc:
+        alias_method :to_ri_cal_occurrence_list_value, :to_ri_cal_date_time_value #:nodoc:
+
+        # Return the natural ri_cal_property for this object
+        def to_ri_cal_property_value(timezone_finder = nil) #:nodoc:
+          to_ri_cal_date_time_value(timezone_finder)
+        end
+        
+        def to_overlap_range_start
+          self
+        end
+        alias_method :to_overlap_range_end, :to_overlap_range_start
+        
+        # Return a copy of this object which will be interpreted as a floating time.
+        def with_floating_timezone
+          dup.set_tzid(:floating)
+        end
+        
+        unless DateTime.instance_methods.map {|selector| selector.to_sym}.include?(:to_date)
+          # Converts self to a Ruby Date object; time portion is discarded
+          def to_date
+            ::Date.new(year, month, day)
+          end
+        end
+        unless DateTime.instance_methods.map {|selector| selector.to_sym}.include?(:to_datetime)
+          # To be able to keep Times, Dates and DateTimes interchangeable on conversions
+          def to_datetime
+            self
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ri_cal/core_extensions/date_time.rb

@@ -0,0 +1,15 @@
+require "ri_cal/core_extensions/date_time/conversions.rb"
+require "ri_cal/core_extensions/time/tzid_access.rb"
+require "ri_cal/core_extensions/time/week_day_predicates.rb"
+require "ri_cal/core_extensions/time/calculations.rb"
+require 'date'
+
+class DateTime #: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::Time::TzidAccess
+  include RiCal::CoreExtensions::DateTime::Conversions
+end

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

@@ -0,0 +1,20 @@
+module RiCal
+  module CoreExtensions #:nodoc:
+    module Object #:nodoc:
+      #- ©2009 Rick DeNatale
+      #- All rights reserved. Refer to the file README.txt for the license
+      #
+      module Conversions #:nodoc:
+        # Used to format rfc2445 output for RiCal
+        def to_rfc2445_string
+          to_s
+        end
+        
+        # Used by RiCal specs returns the receiver
+        def to_ri_cal_ruby_value
+          self
+        end
+      end
+    end
+  end
+end

data/lib/ri_cal/core_extensions/object.rb

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

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

@@ -0,0 +1,57 @@
+module RiCal
+  module CoreExtensions #:nodoc:
+    module String #:nodoc:
+      #- ©2009 Rick DeNatale
+      #- All rights reserved. Refer to the file README.txt for the license
+      #
+      module Conversions #:nodoc:
+        def to_ri_cal_text_property
+           PropertyValue::Text.new(nil, :value => self)
+        end
+        
+        # Parse the receiver as an RiCal::PropertyValue::DateTime
+        def to_ri_cal_date_time_value(timezone_finder = nil)
+          params, value = *Parser.params_and_value(self, :no_leading_semicolon)
+          if PropertyValue::DateTime.valid_string?(value)
+             PropertyValue::DateTime.new(timezone_finder, :params => params, :value => value)
+           else
+             raise InvalidPropertyValue.new("#{self.inspect} is not a valid rfc 2445 date-time")
+           end
+        end
+        
+
+        def to_ri_cal_date_or_date_time_value(timezone_finder = nil)
+          params, value = *Parser.params_and_value(self, :no_leading_semicolon)
+          if PropertyValue::DateTime.valid_string?(value) || PropertyValue::Date.valid_string?(value)
+            PropertyValue.date_or_date_time(timezone_finder, :params => params, :value => value)
+          else
+            raise InvalidPropertyValue.new("#{self.inspect} is not a valid rfc 2445 date or date-time")
+          end
+        end
+
+        # Parse the receiver as an RiCal::PropertyValue::DurationValue
+        def to_ri_cal_duration_value(timezone_finder = nil)
+          params, value = *Parser.params_and_value(self)
+          if PropertyValue::Duration.valid_string?(value)
+            PropertyValue::Duration.new(timezone_finder, :params => params, :value => value)
+          else
+            raise InvalidPropertyValue.new("#{self.inspect} is not a valid rfc 2445 duration")
+          end
+        end
+
+        def to_ri_cal_occurrence_list_value(timezone_finder = nil)
+          params, value = *Parser.params_and_value(self, :no_leading_semicolon)
+          if PropertyValue::DateTime.valid_string?(value)
+            PropertyValue::DateTime.new(timezone_finder, :params => params, :value => value)
+          elsif PropertyValue::Date.valid_string?(value)
+            PropertyValue::Date.new(timezone_finder, :params => params, :value => value)
+          elsif PropertyValue::Period.valid_string?(value)
+            PropertyValue::Period.new(timezone_finder, :params => params, :value => value)
+          else
+            raise "Invalid value for occurrence list #{self.inspect}"
+          end
+        end
+       end
+    end
+  end
+end

data/lib/ri_cal/core_extensions/string.rb

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

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,42 @@
+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(timezone_finder = nil) #:nodoc:
+          RiCal::PropertyValue::DateTime.new(
+               timezone_finder, 
+               :value => strftime("%Y%m%dT%H%M%S"), 
+               :params => {"TZID" => self.tzid || :default})
+        end
+
+        alias_method :to_ri_cal_date_or_date_time_value, :to_ri_cal_date_time_value #:nodoc:
+        alias_method :to_ri_cal_occurrence_list_value, :to_ri_cal_date_time_value #:nodoc:
+
+        # Return the natural ri_cal_property for this object
+        def to_ri_cal_property_value(timezone_finder = nil) #:nodoc:
+          to_ri_cal_date_time_value(timezone_finder)
+        end
+        
+        def to_overlap_range_start
+          to_datetime
+        end
+        
+        alias_method :to_overlap_range_end, :to_overlap_range_start
+        
+        # Return a copy of this object which will be interpreted as a floating time.
+        def with_floating_timezone
+          dup.set_tzid(:floating)
+        end
+        
+        unless Time.instance_methods.map {|selector| selector.to_sym}.include?(:to_datetime)
+          require 'date'
+          ::Time.send(:public, :to_datetime)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+module RiCal
+  module CoreExtensions #:nodoc:
+    module Time #:nodoc:
+      #- ©2009 Rick DeNatale
+      #- All rights reserved. Refer to the file README.txt for the license
+      #
+      # Provides a tzid attribute for ::Time and ::DateTime
+      module TzidAccess
+        # The tzid attribute is used by RiCal, it should be a valid timezone identifier within a calendar,
+        # :floating to indicate a floating time, or nil to use the default timezone in effect
+        #
+        # See PropertyValue::DateTime#default_tzid= and Component::Calendar#tzid=
+        attr_accessor :tzid
+
+        # Convenience method, sets the tzid and returns the receiver
+        def set_tzid(time_zone_identifier)
+          self.tzid = time_zone_identifier
+          self
+        end
+
+        # Predicate indicating whether or not the instance represents a floating time
+        def has_floating_timezone?
+          tzid == :floating
+        end
+
+      end
+    end
+  end
+
+  module TimeWithZoneExtension #:nodoc:
+    def tzid
+      utc? ? "UTC" : time_zone.tzinfo.identifier
+    end
+
+    # Predicate indicating whether or not the instance represents a floating time
+    def has_floating_timezone?
+      false
+    end
+
+    def to_ri_cal_date_time_value(timezone_finder=nil)
+      ::RiCal::PropertyValue::DateTime.new(timezone_finder, :params => {"TZID" => tzid}, :value => strftime("%Y%m%dT%H%M%S"))
+    end
+    alias_method :to_ri_cal_date_or_date_time_value, :to_ri_cal_date_time_value
+    alias_method :to_ri_cal_occurrence_list_value, :to_ri_cal_date_time_value
+  end
+end
+
+if RiCal::TimeWithZone
+  RiCal::TimeWithZone.class_eval {include RiCal::TimeWithZoneExtension}
+end

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

@@ -0,0 +1,55 @@
+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 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,14 @@
+#- ©2009 Rick DeNatale
+#- All rights reserved. Refer to the file README.txt for the license
+#
+require "ri_cal/core_extensions/time/conversions.rb"
+require "ri_cal/core_extensions/time/tzid_access.rb"
+require "ri_cal/core_extensions/time/week_day_predicates.rb"
+require "ri_cal/core_extensions/time/calculations.rb"
+
+class Time #:nodoc:
+  include RiCal::CoreExtensions::Time::WeekDayPredicates
+  include RiCal::CoreExtensions::Time::Calculations  
+  include RiCal::CoreExtensions::Time::Conversions
+  include RiCal::CoreExtensions::Time::TzidAccess
+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"
+