cyclical 0.1.0

data/.gitignore

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

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in cyclical.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2011 Viktor Charypar
+
+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,85 @@
+# Cyclical
+
+Recurring events library for ruby calendar applications.
+
+## About
+
+Cyclical lets you list recurring events with complex recurrence rules like "every 4 years, the first Tuesday after a Monday in November" in a simple way. The API is inspired by [ice_cube](https://github.com/seejohnrun/ice_cube) and uses method chaining for natural rule specification.
+
+You can find out if a given time matches the schedule, list event occurrences or add event duration and list suboccurrences in a given interval, which is handy when you need to trim event occurences to the interval (like rendering a day in a week view of a calendar with events crossing midnight).
+
+Cyclical was originally extracted from a browser based calendar application and is written in ruby. There is a [JavaScript implementation of Cyclical](https://github.com/charypar/cyclical-js) supporting the same features, intended as a front-end counterpart. You can pass data between the implementations using the built-in JSON serialization.
+
+### Missing features and TODO
+
+*  Rule exception dates
+*  Hourly and secondly rules
+
+## Install
+
+Add this line to your application's Gemfile:
+
+    gem 'cyclical'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install cyclical
+
+## Usage
+
+The central thing in Cyclical is the ```Schedule```. Let's take the example of U.S. Presidential Election day from RFC 5545:
+
+```ruby
+  include Cyclical
+
+  date = Time.local(1997, 8, 2, 9, 0, 0)
+  schedule = Schedule.new date, Rule.yearly(4).month(11).weekday(:tue).monthdays(2, 3, 4, 5, 6, 7, 8)
+
+  election_dates = schedule.first(3);
+```
+
+### Creating schedules
+
+Each schedule has a base ```date``` and a recurrence rule. The four supported rules are:
+
+*  daily
+*  weekly
+*  monthly
+*  yearly
+
+with corresponding factory methods on ```Rule```. The factory methods take a single argument - the repetition interval.
+
+The basic recurrence rule matches the original date, i.e. for a yearly rule, the occurences will always happen on the same date. To specify a more complex pattern, you can use filters.
+
+Filters replace the single value (day, month) with a set of values that match. For example, instead of only matching the day of month in of the base date, with the ```monthdays``` filter, you can match multiple month days.
+
+Available filters are:
+
+*  weekday(s)
+*  monthday(s)
+*  yearday(s)
+*  month(s)
+
+Each filter methord takes variable arguments containing integers or string (incl. shortcuts) for a given date component.
+
+You can limit the schedule either by a number of events (using the ```count``` method) or an end date (using the ```stop``` method).
+
+### Querying occurrences and suboccurrences
+
+TODO. See ```lib/cyclical/schedule.rb```
+
+### Serialization and deserialization
+
+TODO. See ```lib/cyclical/schedule.rb```
+
+### More examples
+
+TODO. See RFC 5545 examples in ```spec/schedule_spec.rb```
+
+## License
+
+Cyclical is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/cyclical.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cyclical/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "cyclical"
+  gem.version       = Cyclical::VERSION
+  gem.authors       = ["Viktor Charypar"]
+  gem.email         = ["charypar@gmail.com"]
+  gem.description   = %q{Cyclical lets you list recurring events with complex recurrence rules like "every 4 years, the first Tuesday after a Monday in November" in a simple way.}
+  gem.summary       = %q{Recurring events library for calendar applications.}
+  gem.homepage      = "http://github.com/charypar/cyclical"
+  gem.license       = 'MIT'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_runtime_dependency 'active_support'
+
+  gem.add_development_dependency 'rspec'
+end

data/lib/cyclical/filters/monthdays_filter.rb

@@ -0,0 +1,38 @@
+module Cyclical
+  class MonthdaysFilter
+
+    attr_reader :monthdays
+
+    def initialize(*monthdays)
+      raise ArgumentError, "Specify at least one day of the month" if monthdays.empty?
+
+      @monthdays = monthdays.sort
+    end
+
+    def match?(date)
+      last = date.end_of_month.day
+      (@monthdays.include?(date.day) || @monthdays.include?(date.day - last - 1))
+    end
+
+    def step
+      1.day
+    end
+
+    # FIXME - this can probably be calculated
+    def next(date)
+      until match?(date)
+        date += 1.day
+      end
+
+      date
+    end
+
+    def previous(date)
+      until match?(date)
+        date -= 1.day
+      end
+
+      date
+    end
+  end
+end

data/lib/cyclical/filters/months_filter.rb

@@ -0,0 +1,55 @@
+module Cyclical
+  class MonthsFilter
+
+    MONTH_NAMES = {
+      :jan => 1, :january => 1,
+      :feb => 2, :february => 2,
+      :mar => 3, :march => 3,
+      :apr => 4, :april => 4,
+      :may => 5,
+      :jun => 6, :june => 6,
+      :jul => 7, :july => 7,
+      :aug => 8, :august => 8,
+      :sep => 9, :sept => 9, :september => 9,
+      :oct => 10, :october => 10,
+      :nov => 11, :november => 11,
+      :dec => 12, :december => 12
+    }
+
+    attr_reader :months
+
+    def initialize(*months)
+      raise ArgumentError, "Specify at least one month" if months.empty?
+
+      @months = months.map { |m| m.is_a?(Integer) ? m : MONTH_NAMES[m.to_sym] }.sort
+    end
+
+    def match?(date)
+      @months.include?(date.mon)
+    end
+
+    def step
+      1.month
+    end
+
+    def next(date)
+      return date if match?(date)
+
+      if month = @months.find { |m| m > date.month }
+        date.beginning_of_year + (month - 1).months + date.hour.hours + date.min.minutes + date.sec.seconds
+      else
+        date.beginning_of_year + 1.year + (@months.first - 1).months + date.hour.hours + date.min.minutes + date.sec.seconds
+      end
+    end
+
+    def previous(date)
+      return date if match?(date)
+
+      if month = @months.reverse.find { |m| m < date.month }
+        date.beginning_of_year + month.months - 1.day + date.hour.hours + date.min.minutes + date.sec.seconds
+      else
+        date.beginning_of_year - 1.year + @months.last.months - 1.day + date.hour.hours + date.min.minutes + date.sec.seconds
+      end
+    end
+  end
+end

data/lib/cyclical/filters/weekdays_filter.rb

@@ -0,0 +1,90 @@
+module Cyclical
+  class WeekdaysFilter
+
+    WEEKDAYS = {
+      :su => 0, :sun => 0, :sunday => 0,
+      :mo => 1, :mon => 1, :monday => 1,
+      :tu => 2, :tue => 2, :tuesday => 2,
+      :we => 3, :wed => 3, :wednesday => 3,
+      :th => 4, :thu => 4, :thursday => 4,
+      :fr => 5, :fri => 5, :friday => 5,
+      :sa => 6, :sat => 6, :saturday => 6
+    }
+
+    WEEKDAY_NAMES = [:su, :mo, :tu, :we, :th, :fr, :sa]
+
+    attr_reader :weekdays, :ordered_weekdays, :rule
+
+    def initialize(*weekdays)
+      @rule = weekdays.shift if weekdays.first.is_a?(Rule)
+
+      raise ArgumentError, "Specify at least one weekday" if weekdays.empty?
+      @ordered_weekdays = {}
+
+      if weekdays.last.respond_to?(:has_key?)
+        raise ArgumentError, "No recurrence rule given for ordered weekdays filter" if @rule.nil?
+
+        weekdays.last.each do |day, orders|
+          day = day.is_a?(Integer) ? day : WEEKDAYS[day]
+          orders = [orders] unless orders.respond_to?(:each)
+
+          @ordered_weekdays[WEEKDAY_NAMES[day]] = orders.sort
+        end
+        weekdays = weekdays[0..-2]
+      end
+
+      @weekdays = weekdays.map { |w| w.is_a?(Integer) ? w : WEEKDAYS[w.to_sym] }.sort
+    end
+
+    def match?(date)
+      return true if weekdays.include?(date.wday)
+
+      day = WEEKDAY_NAMES[date.wday]
+      return false if ordered_weekdays[day].nil?
+
+      first, occ, max = order_in_interval(date)
+
+      return (ordered_weekdays[day].include?(occ) || ordered_weekdays[day].include?(occ - max - 1))
+    end
+
+    def step
+      1.day
+    end
+
+    # FIXME - this can probably be calculated
+    def next(date)
+      until match?(date)
+        date += 1.day
+      end
+
+      date
+    end
+
+    def previous(date)
+      until match?(date)
+        date -= 1.day
+      end
+
+      date
+    end
+
+    private
+
+    def order_in_interval(date)
+      case @rule
+      when YearlyRule
+        first = (7 + date.wday - date.beginning_of_year.wday) % 7 + 1
+        occ = (date.yday - first) / 7 + 1
+        max = (date.end_of_year.yday - first) / 7 + 1
+      when MonthlyRule
+        first = (7 + date.wday - date.beginning_of_month.wday) % 7 + 1
+        occ = (date.day - first) / 7 + 1
+        max = (date.end_of_month.day - first) / 7 + 1
+      else
+        raise RuntimeError, "Ordered weekdays filter only supports monthy and yearly rules. (#{@rule.class} given)"
+      end
+
+      [first, occ, max]
+    end
+  end
+end

data/lib/cyclical/filters/yeardays_filter.rb

@@ -0,0 +1,38 @@
+module Cyclical
+  class YeardaysFilter
+
+    attr_reader :yeardays
+
+    def initialize(*yeardays)
+      raise ArgumentError, "Specify at least one day of the month" if yeardays.empty?
+
+      @yeardays = yeardays.sort
+    end
+
+    def match?(date)
+      last = date.end_of_year.yday
+      (@yeardays.include?(date.yday) || @yeardays.include?(date.yday - last - 1))
+    end
+
+    def step
+      1.day
+    end
+
+    # FIXME - traverse the days directly
+    def next(date)
+      until match?(date)
+        date += 1.day
+      end
+
+      date
+    end
+
+    def previous(date)
+      until match?(date)
+        date -= 1.day
+      end
+
+      date
+    end
+  end
+end

data/lib/cyclical/occurrence.rb

@@ -0,0 +1,121 @@
+require 'cyclical/suboccurrence'
+
+module Cyclical
+  # Holds an occurence of a recurrence rule, can compute next and previous and list occurrences
+  class Occurrence
+
+    attr_reader   :rule, :start_time
+    attr_accessor :duration
+
+    def initialize(rule, start_time)
+      @rule = rule
+      @start_time = @rule.match?(start_time, start_time) ? start_time : @rule.next(start_time, start_time)
+    end
+
+    def next_occurrence(after)
+      next_occurrences(1, after).first
+    end
+
+    def next_occurrences(n, after)
+      return [] if @rule.stop && after > @rule.stop
+      time = (after <= @start_time ? @start_time : after)
+      time = @rule.next(time, @start_time) unless @rule.match?(time, @start_time)
+
+      list_occurrences(time) { (n -= 1) >= 0 }
+    end
+
+    def previous_occurrence(before)
+      previous_occurrences(1, before).first
+    end
+
+    def previous_occurrences(n, before)
+      return [] if before <= @start_time
+      time = (@rule.stop.nil? || before < @rule.stop ? before : @rule.stop)
+      time = @rule.previous(time, @start_time) # go back even if before matches the rule (half-open time intervals, remember?)
+
+      list_occurrences(time, :back) { (n -= 1) >= 0 }.reverse
+    end
+
+    def occurrences_between(t1, t2)
+      raise ArgumentError, "Empty time interval" unless t2 > t1
+      return [] if t2 <= @start_time || @rule.stop && t1 >= @rule.stop
+
+      time = (t1 <= @start_time ? @start_time : t1)
+      time = @rule.next(time, @start_time) unless @rule.match?(time, @start_time)
+
+      list_occurrences(time) { |t| t < t2 }
+    end
+
+    def suboccurrences_between(t1, t2)
+      occurrences = occurrences_between(t1 - duration, t2)
+      occurrences.map { |occ| Suboccurrence.find(:occurrence => (occ)..(occ + duration), :interval => t1..t2) }
+    end
+
+    def all
+      if @rule.stop
+        list_occurrences(@start_time) { |t| t < @rule.stop }
+      else
+        n = @rule.count
+        list_occurrences(@start_time) { (n -= 1) >= 0 }
+      end
+    end
+
+    def to_hash
+      @rule.to_hash
+    end
+
+    private
+
+    # yields valid occurrences, return false from the block to stop
+    def list_occurrences(from, direction = :forward, &block)
+      raise ArgumentError, "From #{from} not matching the rule #{@rule} and start time #{@start_time}" unless @rule.match?(from, @start_time)
+
+      results = []
+
+      n, current = init_loop(from, direction)
+      loop do
+        # Rails.logger.debug("Listing occurrences of #{@rule}, going #{direction.to_s}, current: #{current}")
+        # break on schedule span limits
+        return results unless (current >= @start_time) && (@rule.stop.nil? || current < @rule.stop) && (@rule.count.nil? || (n -= 1) >= 0)
+
+        # break on block condition
+        return results unless yield current
+
+        results << current
+
+        # step
+        if direction == :forward
+          current = @rule.next(current, @start_time)
+        else
+          current = @rule.previous(current, @start_time)
+        end
+      end
+    end
+
+    def init_loop(from, direction)
+      return 0, from unless @rule.count # without count limit, life is easy
+
+      # with it, it's... well...
+      if direction == :forward
+        n = 0
+        current = @start_time
+        while current < from
+          n += 1
+          current = @rule.next(current, @start_time)
+        end
+
+        # return the n remaining events
+        return (@rule.count - n), current
+      else
+        n = 0
+        current = @start_time
+        while current < from && (n += 1) < @rule.count
+          current = @rule.next(current, @start_time)
+        end
+
+        # return all events (downloop - yaay, I invented a word - will stop on start time)
+        return @rule.count, current
+      end
+    end
+  end
+end