ri_cal 0.5.0

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,53 @@
+require File.join(File.dirname(__FILE__), %w[.. .. properties timezone_period.rb])
+
+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 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 last_before_local(local_time) #:nodoc:
+          cand_occurrence = nil
+          each do |occurrence|
+            return cand_occurrence if occurrence.dtstart_property > local_time
+            cand_occurrence = occurrence
+          end
+          return cand_occurrence
+        end
+      end
+    end
+  end
+end
+

data/lib/ri_cal/component/todo.rb

@@ -0,0 +1,43 @@
+require File.join(File.dirname(__FILE__), %w[.. properties todo.rb])
+
+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
+
+      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,6 @@
+#- ©2009 Rick DeNatale
+#- All rights reserved. Refer to the file README.txt for the license
+#
+Dir[File.dirname(__FILE__) + "/core_extensions/*.rb"].sort.each do |path|
+  require path
+end

data/lib/ri_cal/core_extensions/array.rb

@@ -0,0 +1,7 @@
+require "#{File.dirname(__FILE__)}/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 "#{File.dirname(__FILE__)}/date/conversions.rb"
+require "#{File.dirname(__FILE__)}/time/week_day_predicates.rb"
+require "#{File.dirname(__FILE__)}/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,61 @@
+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
+        
+        unless defined? ActiveSupport
+          # A method to keep Time, Date and DateTime instances interchangeable on conversions.
+          # In this case, it simply returns +self+.
+          def to_date
+            self
+          end if RUBY_VERSION < '1.9'
+
+          # Converts a Date instance to a Time, where the time is set to the beginning of the day.
+          # The timezone can be either :local or :utc (default :local).
+          #
+          # ==== Examples
+          #   date = Date.new(2007, 11, 10)  # => Sat, 10 Nov 2007
+          #
+          #   date.to_time                   # => Sat Nov 10 00:00:00 0800 2007
+          #   date.to_time(:local)           # => Sat Nov 10 00:00:00 0800 2007
+          #
+          #   date.to_time(:utc)             # => Sat Nov 10 00:00:00 UTC 2007
+          def to_time(form = :local)
+            ::Time.send("#{form}_time", year, month, day)
+          end
+
+          # 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 if RUBY_VERSION < '1.9'
+        end
+      end
+    end
+  end
+end

data/lib/ri_cal/core_extensions/date_time.rb

@@ -0,0 +1,15 @@
+require "#{File.dirname(__FILE__)}/date_time/conversions.rb"
+require "#{File.dirname(__FILE__)}/time/tzid_access.rb"
+require "#{File.dirname(__FILE__)}/time/week_day_predicates.rb"
+require "#{File.dirname(__FILE__)}/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/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
+        
+        # Return a copy of this object which will be interpreted as a floating time.
+        def with_floating_timezone
+          dup.set_tzid(:floating)
+        end
+        
+        unless defined? ActiveSupport
+          # Converts self to a Ruby Date object; time portion is discarded
+          def to_date
+            ::Date.new(year, month, day)
+          end
+
+          # Attempts to convert self to a Ruby Time object; returns self if out of range of Ruby Time class
+          # If self has an offset other than 0, self will just be returned unaltered, since there's no clean way to map it to a Time
+          def to_time
+            self.offset == 0 ? ::Time.utc_time(year, month, day, hour, min, sec) : self
+          end
+
+          # 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/object.rb

@@ -0,0 +1,8 @@
+require "#{File.dirname(__FILE__)}/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/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/string.rb

@@ -0,0 +1,8 @@
+require "#{File.dirname(__FILE__)}/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/string/conversions.rb

@@ -0,0 +1,63 @@
+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:
+        # 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
+ 
+        # code stolen from ActiveSupport Gem
+        unless  ::String.instance_methods.include?("camelize")
+          # Convert the receiver to camelized form
+          # This method duplicates the method provided by ActiveSupport, and will only be defined
+          # by the RiCal gem if it is not already defined.
+          def camelize
+            self.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ri_cal/core_extensions/time.rb

@@ -0,0 +1,13 @@
+require "#{File.dirname(__FILE__)}/time/conversions.rb"
+require "#{File.dirname(__FILE__)}/time/tzid_access.rb"
+require "#{File.dirname(__FILE__)}/time/week_day_predicates.rb"
+require "#{File.dirname(__FILE__)}/time/calculations.rb"
+#- ©2009 Rick DeNatale
+#- All rights reserved. Refer to the file README.txt for the license
+#
+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/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