icalendar-recurrence 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format progress
+<%= "--format Nc" if RUBY_PLATFORM.match(/darwin/) %>

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.1.0
+  - 2.0.0
+  - 1.9.3
+script: bundle exec rspec

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Guardfile

@@ -0,0 +1,5 @@
+guard :rspec, cmd: "bundle exec rspec" do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Jordan Raine
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,86 @@
+# iCalendar Recurrence [![Build Status](https://travis-ci.org/icalendar/icalendar-recurrence.svg?branch=master)](https://travis-ci.org/icalendar/icalendar-recurrence) [![Code Climate](https://codeclimate.com/github/icalendar/icalendar-recurrence.png)](https://codeclimate.com/github/icalendar/icalendar-recurrence) 
+
+Adds event recurrence to the [icalendar gem](https://github.com/icalendar/icalendar). This is helpful in cases where you'd like to parse an ICS and generate a series of event occurrences.
+
+## Install
+
+_Note: This only works against the 2.0beta release of the icalendar gem._
+
+**Until icalendar 2.0beta is released, use git repos in your Gemfile:**
+
+
+```ruby
+gem "icalendar", git: "https://github.com/icalendar/icalendar", branch: "2.0beta"
+gem "icalendar-recurrence", git: "https://github.com/icalendar/icalendar-recurrence"
+```
+
+and run `bundle install` from your shell.
+
+## Usage
+
+### Show occurrences of event between dates
+
+```ruby
+require 'date' # for parse method
+require 'icalendar/recurrence'
+
+calendars = Icalendar.parse(File.read(path_to_ics)) # parse an ICS file
+event = Array(calendars).first.events.first # retrieve the first event
+event.occurrences_between(Date.parse("2014-01-01"), Date.parse("2014-02-01")) # get all occurrence for one month
+```
+
+### Working with occurrences
+
+An event occurrence is a simple struct object with `start_time` and `end_time` methods.
+
+```ruby
+occurrence.start_time # => 2014-02-01 00:00:00 -0800
+occurrence.end_time # => 2014-02-02 00:00:00 -0800
+```
+
+### Daily event with excluded date (inline ICS example)
+
+```ruby
+require 'date' # for parse method
+require 'icalendar/recurrence'
+
+ics_string = <<-EOF
+BEGIN:VCALENDAR
+X-WR-CALNAME:Test Public
+X-WR-CALID:f512e378-050c-4366-809a-ef471ce45b09:101165
+PRODID:Zimbra-Calendar-Provider
+VERSION:2.0
+METHOD:PUBLISH
+BEGIN:VEVENT
+UID:efcb99ae-d540-419c-91fa-42cc2bd9d302
+RRULE:FREQ=DAILY;INTERVAL=1
+SUMMARY:Every day, except the 28th
+DTSTART;VALUE=DATE:20140101
+DTEND;VALUE=DATE:20140102
+STATUS:CONFIRMED
+CLASS:PUBLIC
+X-MICROSOFT-CDO-ALLDAYEVENT:TRUE
+TRANSP:TRANSPARENT
+LAST-MODIFIED:20140113T200625Z
+DTSTAMP:20140113T200625Z
+SEQUENCE:0
+EXDATE;VALUE=DATE:20140128
+END:VEVENT
+END:VCALENDAR
+EOF
+
+# An event that occurs every day, starting January 1, 2014 with one excluded 
+# date. January 28, 2014 will not appear in the occurrences.
+calendars = Icalendar.parse(ics_string)
+every_day_except_jan_28 = Array(calendars).first.events.first
+puts "Every day except January 28, 2014, occurrences from 2014-01-01 to 2014-02-01:"
+puts every_day_except_jan_28.occurrences_between(Date.parse("2014-01-01"), Date.parse("2014-02-01"))
+```
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/icalendar-recurrence/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: [:spec, :build]

data/icalendar-recurrence.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'icalendar/recurrence/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "icalendar-recurrence"
+  spec.version       = Icalendar::Recurrence::VERSION
+  spec.authors       = ["Jordan Raine"]
+  spec.email         = ["jnraine@gmail.com"]
+  spec.summary       = %q{Provides recurrence to icalendar gem.}
+  spec.homepage      = "https://github.com/icalendar/icalendar-recurrence"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency 'icalendar', '~> 2.0.0.beta.1'
+  spec.add_runtime_dependency 'ice_cube', '~> 0.11.1'
+
+  spec.add_development_dependency 'rake', '~> 10.2.1'
+  spec.add_development_dependency 'rspec', '~> 2.14.1'
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'tzinfo', '~> 0.3'
+  spec.add_development_dependency 'timecop', '~> 0.6.3'
+  spec.add_development_dependency 'guard-rspec', '~> 4.2.8'
+  spec.add_development_dependency 'activesupport', '~> 4.0.4'
+  spec.add_development_dependency 'rspec-nc'
+end

data/lib/icalendar-recurrence.rb

@@ -0,0 +1 @@
+require_relative './icalendar/recurrence'

data/lib/icalendar/recurrence.rb

@@ -0,0 +1,12 @@
+require "icalendar"
+require "icalendar/recurrence/version"
+require "icalendar/recurrence/event_extensions"
+require "icalendar/recurrence/weekday_extensions"
+require "icalendar/recurrence/schedule"
+require "icalendar/recurrence/time_util"
+
+module Icalendar
+  module Recurrence
+    # Your code goes here...
+  end
+end

data/lib/icalendar/recurrence/event_extensions.rb

@@ -0,0 +1,36 @@
+module Icalendar
+  module Recurrence
+    module EventExtensions
+      def start
+        dtstart
+      end
+
+      def start_time
+        TimeUtil.to_time(start)
+      end
+
+      def end
+        dtend
+      end
+
+      def occurrences_between(begin_time, closing_time)
+        schedule.occurrences_between(begin_time, closing_time)
+      end
+
+      def schedule
+        @schedule ||= Schedule.new(self)
+      end
+
+      def tzid
+        ugly_tzid = dtstart.ical_params.fetch("tzid", nil)
+        return nil if ugly_tzid.nil?
+
+        Array(ugly_tzid).first.to_s.gsub(/^(["'])|(["'])$/, "")
+      end
+    end
+  end
+
+  class Event
+    include Icalendar::Recurrence::EventExtensions
+  end
+end

data/lib/icalendar/recurrence/schedule.rb

@@ -0,0 +1,148 @@
+require 'ice_cube'
+
+module Icalendar
+  module Recurrence
+    class Occurrence < Struct.new(:start_time, :end_time)
+    end
+
+    class Schedule
+      attr_reader :event
+
+      def initialize(event)
+        @event = event
+      end
+
+      def timezone
+        event.tzid
+      end
+
+      def rrules
+        event.rrule
+      end
+
+      def start_time
+        TimeUtil.to_time(event.start)
+      end
+
+      def end_time
+        TimeUtil.to_time(event.end)
+      end
+
+      def occurrences_between(begin_time, closing_time)
+        ice_cube_occurrences = ice_cube_schedule.occurrences_between(TimeUtil.to_time(begin_time), TimeUtil.to_time(closing_time))
+
+        ice_cube_occurrences.map do |occurrence|
+          convert_ice_cube_occurrence(occurrence)
+        end
+      end
+
+      def convert_ice_cube_occurrence(ice_cube_occurrence)
+        if timezone
+          begin
+            tz = TZInfo::Timezone.get(timezone)
+            start_time = tz.local_to_utc(ice_cube_occurrence.start_time)
+            end_time = tz.local_to_utc(ice_cube_occurrence.end_time)
+          rescue TZInfo::InvalidTimezoneIdentifier => e
+            warn "Unknown TZID specified in ical event (#{timezone.inspect}), ignoring (will likely cause event to be at wrong time!)"
+          end
+        end
+
+        start_time ||= ice_cube_occurrence.start_time
+        end_time ||= ice_cube_occurrence.end_time
+        
+        Icalendar::Recurrence::Occurrence.new(start_time, end_time)
+      end
+
+      def ice_cube_schedule
+        schedule = IceCube::Schedule.new
+        schedule.start_time = start_time
+        schedule.end_time = end_time
+
+        rrules.each do |rrule|
+          ice_cube_recurrence_rule = convert_rrule_to_ice_cube_recurrence_rule(rrule)
+          schedule.add_recurrence_rule(ice_cube_recurrence_rule)
+        end
+
+        event.exdate.each do |exception_date|
+          exception_date = Time.parse(exception_date) if exception_date.is_a?(String)
+          schedule.add_exception_time(TimeUtil.to_time(exception_date))
+        end
+
+        schedule
+      end
+
+      def transform_byday_to_hash(byday_entries)
+        hashable_array = Array(byday_entries).map {|byday| convert_byday_to_ice_cube_day_of_week_hash(byday) }.flatten(1)
+        hash = Hash[*hashable_array]
+
+        if hash.values.include?([0]) # byday interval not specified (e.g., BYDAY=SA not BYDAY=1SA)
+          hash.keys
+        else
+          hash
+        end
+      end
+
+      # private
+
+
+      def convert_rrule_to_ice_cube_recurrence_rule(rrule)
+        ice_cube_recurrence_rule = base_ice_cube_recurrence_rule(rrule.frequency, rrule.interval)
+
+        ice_cube_recurrence_rule.tap do |r|
+          days = transform_byday_to_hash(rrule.by_day)
+
+          r.month_of_year(rrule.by_month) unless rrule.by_month.nil?
+          r.day_of_month(rrule.by_month_day.map(&:to_i)) unless rrule.by_month_day.nil?
+          r.day_of_week(days) if days.is_a?(Hash) and !days.empty?
+          r.day(days) if days.is_a?(Array) and !days.empty?
+          r.until(TimeUtil.to_time(rrule.until)) if rrule.until
+          r.count(rrule.count)
+        end
+
+        ice_cube_recurrence_rule
+      end
+
+      def base_ice_cube_recurrence_rule(frequency, interval)
+        if frequency == "DAILY"
+          IceCube::DailyRule.new(interval)
+        elsif frequency == "WEEKLY"
+          IceCube::WeeklyRule.new(interval)
+        elsif frequency == "MONTHLY"
+          IceCube::MonthlyRule.new(interval)
+        elsif frequency == "YEARLY"
+          IceCube::YearlyRule.new(interval)
+        else
+          raise "Unknown frequency: #{rrule.frequency}"
+        end
+      end
+
+      def convert_byday_to_ice_cube_day_of_week_hash(ical_byday)
+        data = parse_ical_byday(ical_byday)
+        day_code = data.fetch(:day_code)
+        position = data.fetch(:position)
+
+        day_symbol = case day_code.to_s
+        when "SU" then :sunday
+        when "MO" then :monday
+        when "TU" then :tuesday
+        when "WE" then :wednesday
+        when "TH" then :thursday
+        when "FR" then :friday
+        when "SA" then :saturday
+        else
+          raise ArgumentError.new "Unexpected ical_day: #{ical_day.inspect}"
+        end
+
+        [day_symbol, Array(position)]
+      end
+
+      # Parses ICAL BYDAY value to day and position array
+      # 1SA => {day_code: "SA", position: 1}
+      # MO  => {day_code: "MO", position: nil
+      def parse_ical_byday(ical_byday)
+        match = ical_byday.match(/(\d*)([A-Z]{2})/)
+        {day_code: match[2], position: match[1].to_i}
+      end
+    end
+  end
+end

data/lib/icalendar/recurrence/time_util.rb

@@ -0,0 +1,94 @@
+require 'tzinfo'
+
+module Icalendar
+  module Recurrence
+    module TimeUtil
+      def datetime_to_time(datetime)
+        raise ArgumentError, "Unsupported DateTime object passed (must be Icalendar::Values::DateTime#{datetime.class} passed instead)" unless supported_datetime_object?(datetime)
+        offset = timezone_offset(datetime.ical_params["tzid"], moment: datetime.to_date)
+        offset ||= datetime.strftime("%:z")
+
+        Time.new(datetime.year, datetime.month, datetime.mday, datetime.hour, datetime.min, datetime.sec, offset)
+      end
+
+      def date_to_time(date)
+        raise ArgumentError, "Must pass a Date object (#{date.class} passed instead)" unless supported_date_object?(date)
+        Time.new(date.year, date.month, date.mday)
+      end
+
+      def to_time(time_object)
+        if supported_time_object?(time_object)
+          time_object
+        elsif supported_datetime_object?(time_object)
+          datetime_to_time(time_object)
+        elsif supported_date_object?(time_object)
+          date_to_time(time_object)
+        elsif time_object.is_a?(String)
+          Time.parse(time_object)
+        else
+          raise ArgumentError, "Unsupported time object passed: #{time_object.inspect}"
+        end
+      end
+
+      # Calculates offset for given timezone ID (tzid). Optional, specify a 
+      # moment in time to calulcate this offset. If no moment is specified,
+      # use the current time.
+      # 
+      # # If done before daylight savings:
+      # TimeUtil.timezone_offset("America/Los_Angeles") => -08:00
+      # # Or after:
+      # TimeUtil.timezone_offset("America/Los_Angeles", moment: Time.parse("2014-04-01")) => -07:00
+      # 
+      def timezone_offset(tzid, options = {})
+        tzid = Array(tzid).first
+        options = {moment: Time.now}.merge(options)
+        moment = options.fetch(:moment)
+        utc_moment = to_time(moment.clone).utc
+        tzid = tzid.to_s.gsub(/^(["'])|(["'])$/, "")
+        utc_offset =  TZInfo::Timezone.get(tzid).period_for_utc(utc_moment).utc_total_offset # this seems to work, but I feel like there is a lurking bug
+        hour_offset = utc_offset/60/60
+        hour_offset = "+#{hour_offset}" if hour_offset >= 0
+        match = hour_offset.to_s.match(/(\+|-)(\d+)/)
+        "#{match[1]}#{match[2].rjust(2, "0")}:00"
+      rescue TZInfo::InvalidTimezoneIdentifier => e
+        nil
+      end
+
+      # See #timezone_offset_at_moment
+      def timezone_to_hour_minute_utc_offset(tzid, moment = Time.now)
+        timezone_offset(tzid, moment: moment)
+      end
+
+      def supported_date_object?(time_object)
+        time_object.is_a?(Date) or time_object.is_a?(Icalendar::Values::Date)
+      end
+
+      def supported_datetime_object?(time_object)
+        time_object.is_a?(Icalendar::Values::DateTime) 
+      end
+
+      def supported_time_object?(time_object)
+        time_object.is_a?(Time)
+      end
+
+      # Replaces the existing offset with one associated with given TZID. Does
+      # not change hour of day, only the offset. For example, if given a UTC 
+      # time of 8am, the returned time object will still be 8am but in another
+      # timezone. See test for working examples.
+      def force_zone(time, tzid)
+        offset = timezone_offset(tzid, moment: time)
+        raise ArgumentError.new("Unknown TZID: #{tzid}") if offset.nil?
+        Time.new(time.year, time.month, time.mday, time.hour, time.min, time.sec, offset)
+      end
+
+      extend self
+    end
+  end
+end
+
+# Should we move this to a module and extend time?
+class Time
+  def force_zone(tzid)
+    TimeUtil.force_zone(self, tzid)
+  end
+end