cyclical 0.1.0

data/lib/cyclical/rule.rb

@@ -0,0 +1,235 @@
+require 'cyclical/filters/months_filter'
+require 'cyclical/filters/weekdays_filter'
+require 'cyclical/filters/monthdays_filter'
+require 'cyclical/filters/yeardays_filter'
+
+module Cyclical
+
+  # Rules describe the basic recurrence patterns (frequency and interval) and hold the set of rules (called filters)
+  # that a candidate date must match to be included into the recurrence set.
+  # Rules can align a date to a closest date (in the past or in the future) matching all the filters with respect to
+  # selected start date of the recurrence.
+  class Rule
+
+    attr_reader :interval
+
+    def initialize(interval = 1)
+      @interval = interval
+      @filters = []
+      @filter_map = {}
+    end
+
+    # rule specification DSL
+
+    def count(n = nil)
+      return @count unless n
+
+      @count = n
+      self
+    end
+
+    def stop(t = nil)
+      return @stop unless t
+
+      @stop = t
+      self
+    end
+
+    def months(*months)
+      raise RuntimeError, "Months filter already set" if @filter_map[:month]
+
+      f = MonthsFilter.new(*months)
+      @filters << f
+      @filter_map[:months] = f
+
+      self
+    end
+    alias :month :months
+
+    def weekdays(*weekdays)
+      raise RuntimeError, "weekdays filter already set" if @filter_map[:weekdays]
+      weekdays = [self] + weekdays
+
+      f = WeekdaysFilter.new(*weekdays)
+      @filters << f
+      @filter_map[:weekdays] = f
+
+      self
+    end
+    alias :weekday :weekdays
+
+    def monthdays(*monthdays)
+      raise RuntimeError, "monthdays filter already set" if @filter_map[:monthdays]
+
+      f = MonthdaysFilter.new(*monthdays)
+      @filters << f
+      @filter_map[:monthdays] = f
+
+      self
+    end
+    alias :monthday :monthdays
+
+    def yeardays(*yeardays)
+      raise RuntimeError, "yeardays filter already set" if @filter_map[:yeardays]
+
+      f = YeardaysFilter.new(*yeardays)
+      @filters << f
+      @filter_map[:yeardays] = f
+
+      self
+    end
+    alias :yearday :yeardays
+
+
+    def filters(kind = nil)
+      return @filters if kind.nil?
+
+      @filter_map[kind.to_sym]
+    end
+
+    # rule API
+
+    def finite?
+      !infinite?
+    end
+
+    def infinite?
+      @count.nil? && @stop.nil?
+    end
+
+    # returns true if time is aligned to the recurrence pattern and matches all the filters
+    def match?(time, base)
+      aligned?(time, base) && @filters.all? { |f| f.match?(time) }
+    end
+
+    # get next date matching the rule (not checking limits). Returns next occurrence even if +time+ matches the rule.
+    def next(time, base)
+      current = time
+      until match?(current, base) && current > time
+        pot_next = align(potential_next(current, base), base)
+        pot_next += min_step if pot_next == current
+
+        current = pot_next
+      end
+
+      current
+    end
+
+    # get previous date matching the rule (not checking limits). Returns next occurrence even if +time+ matches the rule.
+    def previous(time, base)
+      current = time
+      until match?(current, base) && current < time
+        pot_prev = align(potential_previous(current, base), base)
+        pot_prev -= min_step if pot_prev == current
+
+        current = pot_prev
+      end
+
+      current
+    end
+
+    # basic building blocks of the computations
+
+    def aligned?(time, base)
+      # for subclass to override
+    end
+
+    def step
+      # for subclass to override
+    end
+
+    def to_hash
+      hash = { :freq => self.class.to_s.underscore.split('/').last.split('_').first, :interval => @interval }
+
+      hash[:count] = @count if @count
+      hash[:stop] = @stop if @stop
+
+      hash[:weekdays] = (filters(:weekdays).weekdays + [filters(:weekdays).ordered_weekdays]) if filters(:weekdays)
+      hash[:monthdays] = filters(:monthdays).monthdays if filters(:monthdays)
+      hash[:yeardays] = filters(:yeardays).yeardays if filters(:yeardays)
+      hash[:months] = filters(:months).months if filters(:months)
+
+      hash
+    end
+
+    def to_json
+      to_hash.to_json
+    end
+
+    # factory methods
+
+    class << self
+      def daily(interval = 1)
+        DailyRule.new(interval)
+      end
+
+      def yearly(interval = 1)
+        YearlyRule.new(interval)
+      end
+
+      def weekly(interval = 1)
+        WeeklyRule.new(interval)
+      end
+
+      def monthly(interval = 1)
+        MonthlyRule.new(interval)
+      end
+
+      def from_hash(hash)
+        raise "Bad Hash format: '#{hash.inspect}'" unless hash[:freq] && hash[:interval]
+
+        rule = self.send(hash[:freq].to_sym, hash[:interval].to_i)
+
+        rule.count(hash[:count]) if hash.has_key?(:count)
+        rule.stop(hash[:stop]) if hash.has_key?(:stop)
+
+        rule.weekdays(*hash[:weekdays]) if hash.has_key?(:weekdays)
+        rule.monthdays(*hash[:monthdays]) if hash.has_key?(:monthdays)
+        rule.yeardays(*hash[:yeardays]) if hash.has_key?(:yeardays)
+        rule.months(*hash[:months]) if hash.has_key?(:months)
+
+        rule
+      end
+
+      def from_json(json)
+        h = JSON.parse(json)
+        h['stop'] = Time.parse(h['stop']) if h['stop']
+
+        from_hash(h.symbolize_keys)
+      end
+    end
+
+    protected
+
+    # Next comes the heart of all the calculations
+
+    # Find a potential next date matching the rule as a maximum of next
+    # valid dates from all the filters. Subclasses should add a check of
+    # recurrence pattern match
+    def potential_next(current, base)
+      @filters.map { |f| f.next(current) }.max || current
+    end
+
+    # Find a potential previous date matching the rule as a minimum of previous
+    # valid dates from all the filters. Subclasses should add a check of
+    # recurrence pattern match
+    def potential_previous(current, base)
+      @filters.map { |f| f.previous(current) }.min || current
+    end
+
+    # Should return a time aligned to the base in the rule interval resolution, e.g.:
+    # - in a daily rule a time on the same day with a correct hour, minute and second
+    # - in a weekly rule a time in the same week with a correct weekday, hour, minute and second
+    def align(time, base)
+      raise NotImplementedError, "#{self.class}.align should be overriden and return a time in the period of time parameter, aligned to base"
+    end
+
+    # Minimal step of all the filters and the recurrence rule. This allows the
+    # next/previous calculation to move a sane amount of time forward when all
+    # the filters and the rule match but the candidate is before/after the
+    # requested time (which is caused by date alignment)
+    def min_step
+      @min_step ||= ([step] + @filters.map { |f| f.step }).min
+    end
+  end
+end

data/lib/cyclical/rules/daily_rule.rb

@@ -0,0 +1,49 @@
+require 'cyclical/rule'
+
+module Cyclical
+  # holds daily rule configuration
+  class DailyRule < Rule
+
+    def aligned?(time, base)
+      return false unless (base.to_date - time.to_date) % @interval == 0
+      return false unless [time.hour, time.min, time.sec] == [base.hour, base.min, base.sec]
+
+      true
+    end
+
+    def step
+      @interval.days
+    end
+
+    protected
+
+    def potential_next(current, base)
+      candidate = super(current, base)
+
+      rem = (base.to_date - candidate.to_date) % @interval
+
+      return candidate if rem == 0
+
+      rem += @interval if rem < 0
+      candidate.beginning_of_day + rem.days
+    end
+
+    def potential_previous(current, base)
+      candidate = super(current, base)
+
+      rem = (base.to_date - candidate.to_date) % @interval
+
+      return candidate if rem == 0
+
+      rem += @interval if rem < 0
+      candidate.beginning_of_day + (rem - @interval).days
+    end
+
+    def align(time, base)
+      # compensate crossing DST barrier (oh my...)
+      offset = time.beginning_of_day.utc_offset
+      time = time.beginning_of_day + base.hour.hours + base.min.minutes + base.sec.seconds
+      time += (offset - time.utc_offset)
+    end
+  end
+end

data/lib/cyclical/rules/monthly_rule.rb

@@ -0,0 +1,56 @@
+require 'cyclical/rule'
+
+module Cyclical
+  # holds weekly rule configuration
+  class MonthlyRule < Rule
+
+    # check if time is aligned to a base time, including interval check
+    def aligned?(time, base)
+      return false unless ((12 * base.year + base.mon) - (12 * time.year + time.mon)) % @interval == 0
+      return false unless [time.hour, time.min, time.sec] == [base.hour, base.min, base.sec] # the shortest filter we support is for days
+      return false unless base.day == time.day || monthday_filters
+
+      true
+    end
+
+    # default step of the rule
+    def step
+      @interval.months
+    end
+
+    protected
+
+    def potential_next(current, base)
+      candidate = super(current, base)
+
+      rem = ((12 * base.year + base.mon) - (12 * candidate.year + candidate.mon)) % @interval
+      return candidate if rem == 0
+
+      (candidate + rem.months).beginning_of_month
+    end
+
+    def potential_previous(current, base)
+      candidate = super(current, base)
+
+      rem = ((12 * base.year + base.mon) - (12 * candidate.year + candidate.mon)) % @interval
+      return candidate if rem == 0
+
+      (candidate + rem.months - step).end_of_month
+    end
+
+    def align(time, base)
+      time = time.beginning_of_month + (base.day - 1).days unless time.day == base.day || monthday_filters
+
+      # compensate crossing DST barrier (oh my...)
+      offset = time.beginning_of_day.utc_offset
+      time = time.beginning_of_day + base.hour.hours + base.min.minutes + base.sec.seconds
+      time += (offset - time.utc_offset)
+
+      time
+    end
+
+    def monthday_filters
+      filters(:weekdays) || filters(:monthdays) || filters(:yeardays) || filters(:weeks) || filters(:months)
+    end
+  end
+end

data/lib/cyclical/rules/weekly_rule.rb

@@ -0,0 +1,58 @@
+require 'cyclical/rule'
+
+module Cyclical
+  # holds daily rule configuration
+  class WeeklyRule < Rule
+
+    # check if time is aligned to a base time, including interval check
+    def aligned?(time, base)
+      return false unless ((base.beginning_of_week - time.beginning_of_week) / 604800).to_i % @interval == 0 # 604800 = 7.days
+      return false unless [time.hour, time.min, time.sec] == [base.hour, base.min, base.sec] # the shortest filter we support is for days
+
+      return false unless base.wday == time.wday || weekday_filters
+
+      # wow, passed every test
+      true
+    end
+
+    # default step of the rule
+    def step
+      @interval.weeks
+    end
+
+    protected
+
+    def potential_next(current, base)
+      candidate = super(current, base)
+
+      rem = ((base.beginning_of_week - candidate.beginning_of_week) / 604800).to_i % @interval
+      return candidate if rem == 0
+
+      (candidate + rem.weeks).beginning_of_week
+    end
+
+    def potential_previous(current, base)
+      candidate = super(current, base)
+
+      rem = ((base.beginning_of_week - candidate.beginning_of_week) / 604800).to_i % @interval
+      return candidate if rem == 0
+
+      (candidate + rem.weeks - step).end_of_week
+    end
+
+    def align(time, base)
+      time = time.beginning_of_week + base.wday.days unless time.wday == base.wday || weekday_filters
+
+      # compensate crossing DST barrier (oh my...)
+      offset = time.beginning_of_day.utc_offset
+      time = time.beginning_of_day + base.hour.hours + base.min.minutes + base.sec.seconds
+      time += (offset - time.utc_offset)
+
+      time
+    end
+
+    def weekday_filters
+      filters(:weekdays) || filters(:monthdays) || filters(:yeardays) || filters(:yeardays) || filters(:weeks) || filters(:months)
+    end
+  end
+end

data/lib/cyclical/rules/yearly_rule.rb

@@ -0,0 +1,66 @@
+require 'cyclical/rule'
+
+module Cyclical
+  # holds daily rule configuration
+  class YearlyRule < Rule
+
+    # check if time is aligned to a base time, including interval check
+    def aligned?(time, base)
+      return false unless (base.year - time.year).to_i % @interval == 0
+      return false unless [time.hour, time.min, time.sec] == [base.hour, base.min, base.sec] # the shortest filter we support is for days
+      return false unless time.day == base.day || filters(:weekdays) || filters(:monthdays) || filters(:yeardays)
+      return false unless time.month == base.month || filters(:yeardays) || filters(:weeks) || filters(:months)
+
+      # wow, passed every test
+      true
+    end
+
+    # default step of the rule
+    def step
+      @interval.years
+    end
+
+    private
+
+    # closest valid date
+    def potential_next(current, base)
+      candidate = super(current, base)
+      return candidate if (base.year - candidate.year).to_i % @interval == 0
+
+      years = ((base.year - candidate.year).to_i % @interval)
+
+      (candidate + years.years).beginning_of_year
+    end
+
+    def potential_previous(current, base)
+      candidate = super(current, base)
+      return candidate if (base.year - candidate.year).to_i % @interval == 0
+
+      years = ((base.year - candidate.year).to_i % @interval)
+
+      (candidate + (years - @interval).years).end_of_year
+    end
+
+    def align(time, base)
+      day = (day_filters ? time.day : base.day)
+      mon = (month_filters ? time.mon : base.mon)
+
+      time = time.beginning_of_year + (mon - 1).months + (day - 1).days
+
+      # compensate crossing DST barrier (oh my...)
+      offset = time.beginning_of_day.utc_offset
+      time = time.beginning_of_day + base.hour.hours + base.min.minutes + base.sec.seconds
+      time += (offset - time.utc_offset)
+
+      time
+    end
+
+    def day_filters
+      filters(:weekdays) || filters(:monthdays) || filters(:yeardays)
+    end
+
+    def month_filters
+      filters(:weekdays) || filters(:yeardays) || filters(:weeks) || filters(:months)
+    end
+  end
+end

data/lib/cyclical/schedule.rb

@@ -0,0 +1,125 @@
+require 'time'
+
+require 'cyclical/rule'
+
+require 'cyclical/rules/daily_rule'
+require 'cyclical/rules/weekly_rule'
+require 'cyclical/rules/monthly_rule'
+require 'cyclical/rules/yearly_rule'
+
+require 'cyclical/occurrence'
+
+module Cyclical
+  class Schedule
+
+    attr_reader :start_time
+    attr_accessor :end_time
+
+    def initialize(start_time, rule = nil)
+      @occurrence = Occurrence.new rule, start_time unless rule.nil?
+      @start_time = @occurrence ? @occurrence.start_time : start_time
+    end
+
+    def rule=(rule)
+      @occurrence = (rule.nil? ? nil : Occurrence.new(rule, start_time))
+      @occurrence.duration = end_time ? (end_time - start_time) : 0
+    end
+
+    def rule
+      @occurrence.nil? ? nil : @occurrence.rule
+    end
+
+    def end_time=(time)
+      raise "End time is before start time" if time < @start_time
+      @end_time = time
+      @occurrence.duration = (time - start_time) unless @occurrence.nil?
+
+      time
+    end
+
+    # query interface
+
+    def first(n)
+      return [start_time] if @occurrence.nil?
+
+      @occurrence.next_occurrences(n, start_time)
+    end
+
+    # first occurrence in [time, infinity)
+    def next_occurrence(time)
+      return (start_time < time ? nil : start_time) if @occurrence.nil?
+
+      @occurrence.next_occurrence(time)
+    end
+
+    # last occurrence in (-infinity, time)
+    def previous_occurrence(time)
+      return (start_time >= time ? nil : start_time) if @occurrence.nil?
+
+      @occurrence.previous_occurrence(time)
+    end
+
+    def occurrences(end_time = nil)
+      raise ArgumentError, "You have to specify end time for an infinite schedule occurrence listing" if end_time.nil? && @occurrence && @occurrence.rule.infinite?
+
+      if end_time
+        occurrences_between(start_time, end_time)
+      else
+        return [start_time] if @occurrence.nil?
+
+        @occurrence.all
+      end
+    end
+
+    # occurrences in [t1, t2)
+    def occurrences_between(t1, t2)
+      return ((start_time < t1 || @start_time >= t2) ? [] : [start_time]) if @occurrence.nil?
+
+      @occurrence.occurrences_between(t1, t2)
+    end
+
+    def suboccurrences_between(t1, t2)
+      raise RuntimeError, "Schedule must have an end time to compute suboccurrences" unless end_time
+
+      return [Suboccurrence.find(:occurrence => start_time..end_time, :interval => t1..t2)] if @occurrence.nil?
+
+      @occurrence.suboccurrences_between(t1, t2)
+    end
+
+    def to_hash
+      hash = @occurrence.nil? ? {} : @occurrence.to_hash.clone
+
+      hash[:start] = start_time
+      hash[:end] = end_time if end_time
+
+      hash
+    end
+
+    def to_json
+      to_hash.to_json
+    end
+
+    def self.from_hash(hash)
+      rule = hash.clone
+      start_time = hash.delete(:start)
+      end_time = hash.delete(:end)
+
+      rule = hash[:freq] && hash[:interval] ? Rule.from_hash(hash) : nil
+
+      s = Schedule.new start_time, rule
+      s.end_time = end_time
+
+      s
+    end
+
+    def self.from_json(json)
+      h = JSON.parse(json)
+
+      h['start'] = Time.parse(h['start']) if h['start']
+      h['end'] = Time.parse(h['end']) if h['end']
+      h['stop'] = Time.parse(h['stop']) if h['stop']
+
+      from_hash(h.symbolize_keys)
+    end
+  end
+end

data/lib/cyclical/suboccurrence.rb

@@ -0,0 +1,48 @@
+module Cyclical
+  # Holds suboccurrence of a schedule, i.e. time interval which is a subinterval of a single occurrence.
+  # This is used to find actual time spans to display in a given time interval (for example in a calendar)
+  class Suboccurrence
+    attr_reader :start, :end, :occurrence_start, :occurrence_end
+
+    alias :occurrence_start? :occurrence_start
+    alias :occurrence_end? :occurrence_end
+
+    # factory method for finding suboccurrence of a single occurrence with an interval, with the ability to return nil
+    # This might be a totally bad idea, I'm not sure right now really...
+    def self.find(attrs)
+      raise ArgumentError, "Missing occurrence" unless (occurrence = attrs[:occurrence]).is_a?(Range)
+      raise ArgumentError, "Missing interval" unless (interval = attrs[:interval]).is_a?(Range)
+
+      return nil if occurrence.last <= interval.first || occurrence.first >= interval.last
+
+      suboccurrence = {}
+
+      if occurrence.first < interval.first
+        suboccurrence[:start] = interval.first
+        suboccurrence[:occurrence_start] = false
+      else
+        suboccurrence[:start] = occurrence.first
+        suboccurrence[:occurrence_start] = true
+      end
+
+      if occurrence.last > interval.last
+        suboccurrence[:end] = interval.last
+        suboccurrence[:occurrence_end] = false
+      else
+        suboccurrence[:end] = occurrence.last
+        suboccurrence[:occurrence_end] = true
+      end
+
+      return new(suboccurrence)
+    end
+
+    private
+
+    def initialize(attrs)
+      @start = attrs[:start]
+      @end = attrs[:end]
+      @occurrence_start = attrs[:occurrence_start]
+      @occurrence_end = attrs[:occurrence_end]
+    end
+  end
+end

data/lib/cyclical/version.rb

@@ -0,0 +1,3 @@
+module Cyclical
+  VERSION = "0.1.0"
+end

data/lib/cyclical.rb

@@ -0,0 +1,12 @@
+require 'active_support/core_ext/time/acts_like'
+require 'active_support/core_ext/time/calculations'
+require 'active_support/core_ext/integer/time'
+require 'active_support/core_ext/numeric/time'
+
+require 'json'
+
+require "cyclical/version"
+require "cyclical/schedule"
+
+module Cyclical
+end

data/spec/filters/monthdays_filter_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+describe  do
+  before do
+    @filter = MonthdaysFilter.new(1, 3, -5)
+  end
+
+  it "should accept weekdays as constructor arguments" do
+    @filter.monthdays.should == [-5, 1, 3]
+  end
+
+
+  it "should match only the selected monthdays" do
+    filter = MonthdaysFilter.new(1, 3, 17, -6)
+
+    filter.match?(Time.utc(2000, 1, 1)).should be_true
+    filter.match?(Time.utc(2000, 1, 3)).should be_true
+    filter.match?(Time.utc(2000, 1, 17)).should be_true
+    filter.match?(Time.utc(2000, 1, 26)).should be_true
+
+    filter.match?(Time.utc(2000, 2, 26)).should be_false
+
+    filter.match?(Time.utc(2000, 1, 2)).should be_false
+    filter.match?(Time.utc(2000, 1, 4)).should be_false
+    filter.match?(Time.utc(2000, 1, 5)).should be_false
+    filter.match?(Time.utc(2000, 1, 6)).should be_false
+    filter.match?(Time.utc(2000, 1, 8)).should be_false
+    filter.match?(Time.utc(2000, 1, 27)).should be_false
+  end
+
+  it "should provide next valid date" do
+    @filter.next(Time.utc(2010, 1, 1, 21, 13, 11)).should == Time.utc(2010, 1, 1, 21, 13, 11)
+    @filter.next(Time.utc(2010, 1, 2, 21, 13, 11)).should == Time.utc(2010, 1, 3, 21, 13, 11)
+    @filter.next(Time.utc(2010, 1, 18, 21, 13, 11)).should == Time.utc(2010, 1, 27, 21, 13, 11)
+  end
+end