vrinek-periodicity 0.1.1

data/History.txt

@@ -0,0 +1,4 @@
+=== 0.1 2009-08-06
+
+* 1 major enhancement:
+  * Initial release

data/Manifest.txt

@@ -0,0 +1,14 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+lib/periodicity.rb
+lib/periodicity/period.rb
+script/console
+script/destroy
+script/generate
+spec/periodicity_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/rspec.rake

data/PostInstall.txt

@@ -0,0 +1,2 @@
+
+For more information on periodicity, see http://github.com/vrinek/periodicity/

data/README.rdoc

@@ -0,0 +1,33 @@
+= periodicity
+
+* http://github.com/vrinek/periodicity
+
+== DESCRIPTION:
+
+Helps calculate the next run for schedulers using a human readable syntax.
+
+== SYNOPSIS:
+
+  period = Period.new(Time.now).every(2).hours.at(20).from(10).to(15)
+means: every 2 hours at :20 from 10:00 to 15:00 (10:20, 12:20, 14:20)
+  
+  period.next_run # returns the next calculated time as a Time object
+  period.next_run(1) # skips 1 run (as of 0.1, it behaves buggy with from and to limits)
+  
+  Period.new.every(:half).hour # every 30 minutes
+  Period.every.week # every week
+  Period.every(5).seconds # every 5 seconds
+
+== REQUIREMENTS:
+
+* active support (not sure about the exact version yet)
+
+== INSTALL:
+
+* gem sources -a http://gems.github.com
+* sudo gem install vrinek-periodicity
+
+== TODO:
+
+* support "overnight" limits (from 22:00 tonight to 02:00 tomorrow) like:
+    Period.every.hour.from(20).to(2)

data/Rakefile

@@ -0,0 +1,27 @@
+require 'rubygems'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+require './lib/periodicity'
+
+Hoe.plugin :newgem
+# Hoe.plugin :website
+# Hoe.plugin :cucumberfeatures
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.spec 'periodicity' do
+  self.developer              'Kostas Karachalios', 'kostas.karachalios@me.com'
+  self.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
+  self.extra_deps           = [['activesupport','>= 2.3.2']]
+  self.extra_rdoc_files     = ['README.rdoc']
+  self.url                  = 'http://github.com/vrinek/periodicity'
+
+end
+
+require 'newgem/tasks'
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+remove_task :default
+task :default => :spec

data/lib/periodicity.rb

@@ -0,0 +1,9 @@
+$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'rubygems'
+require 'activesupport'
+require 'periodicity/period'
+
+module Periodicity
+  VERSION = '0.1.1'
+end

data/lib/periodicity/period.rb

@@ -0,0 +1,265 @@
+class Period
+  DAY_PERIODS = {
+    "morning" => 9,
+    "noon" => 12,
+    "afternoon" => 19,
+    "midnight" => 0
+  }
+  
+=begin rdoc
+  Initializes a new Period object with the last_run used for the next_run calculations
+  
+  A Period object needs at least an every and time period (minutes, hours etc) to functions properly:
+    Period.new.every.day
+    Period.new(2.hours.ago).every(4).hours
+  
+  If last_run is nil, next_run will always return Time.now
+=end
+  def initialize(last_run = nil)
+    @last_run = last_run
+    @at = 0
+  end
+  
+=begin rdoc
+  Sets the interval at which the runs should be calculated:
+  
+    every.day
+    every(20).minutes
+    every(2).hours
+=end
+  def every(int = 1)
+    @interval = int
+    return self
+  end
+  
+=begin rdoc
+  Sets the scope to one week so that <tt>every(2).weeks</tt> means "every 2 weeks"
+=end
+  def weeks
+    @scope = 1.week
+    reset_on_base 7
+    
+    return self
+  end
+  alias_method :week, :weeks
+  
+=begin rdoc
+  Sets the scope to one day so that <tt>every(4).days</tt> means "every 4 days"
+=end
+  def days
+    @scope = 1.days
+    reset_on_base 24
+    
+    return self
+  end
+  alias_method :day, :days
+  
+=begin rdoc
+  Sets the scope to one hour so that <tt>every(6).hours</tt> means "every 6 hours"
+=end
+  def hours
+    @scope = 1.hour
+    reset_on_base 60
+    
+    return self
+  end
+  alias_method :hour, :hours
+  
+=begin rdoc
+  Sets the scope to one minute so that <tt>every(20).minutes</tt> means "every 20 minutes"
+=end
+  def minutes
+    @scope = 1.minute
+    reset_on_base 60
+    
+    return self
+  end
+  alias_method :minute, :minutes
+  
+=begin rdoc
+  Sets the scope to one second so that <tt>every(5).seconds</tt> means "every 5 seconds"
+=end
+  def seconds
+    @scope = 1.second
+    reset_on_base false
+    
+    return self
+  end
+  alias_method :second, :seconds
+  
+=begin rdoc
+  Sets the from limit based on the scope:
+    every(2).hours.from(8) # means "every 2 hours beginning from 8:00"
+=end
+  def from(time)
+    raise "From can't be after to" if @to and @to < time
+    
+    @from = time
+    return self
+  end
+  
+=begin rdoc
+  Sets the to limit based on the scope:
+    every(2).hours.to(12) # means "every 2 hours until 12:00"
+=end
+  def to(time)
+    raise "To can't be before from" if @from and time < @from
+    
+    @to = time
+    return self
+  end
+  
+=begin rdoc
+  Sets a specific "sub-time" for the next_run:
+    every(2).hours.at(15) # means "every 2 hours at the first quarter of each" e.g. 12:15, 14:15, 16:15
+  
+  NOTE: when using at and from, to limits together the limits *always* calculate at 0 "sub-time":
+    every(2).hours.at(15).from(12).to(16) # will return 12:15, 14:15 but not 16:15 because the to limit ends at 16:00
+=end
+  def at(time)
+    unless time.is_a?(Integer)
+      time = case time.to_s
+      when /^\d+:00$/
+        time[/^\d+/].to_i
+      when /^\d+:\d{2}$/
+        raise 'Precise timing like "20:15" is not yet supported'
+      when /^(noon|afternoon|midnight|morning)$/
+        DAY_PERIODS[time.to_s]
+      else
+        time.to_i
+      end
+    end
+    
+    @at = time
+    return self
+  end
+  
+=begin rdoc
+  This return a Time object for the next calculated time:
+    now = "Aug 05 14:40:23 2009".to_time
+    Period.new(now).every(2).hours.next_run # => Wed Aug 05 16:00:00 UTC 2009
+    
+  Note that it round all "sub-time" to 0 by default (can be overriden with at)
+=end
+  def next_run(skip = 0)
+    return Time.now unless @last_run
+    
+    @next_run = @last_run
+    
+    if @scope and @interval
+      @next_run += @interval * @scope
+      
+      calc_precision
+      
+      calc_limits
+      
+      unless skip.zero?
+        @next_run += @interval * @scope * skip
+
+        calc_limits
+      end
+    else
+      raise 'No proper period specified'
+    end
+    
+    return @next_run
+  end
+  
+  private
+  
+  def reset_on_base(base)
+    @interval = 1 unless base
+    
+    @interval = case @interval.to_s
+    when /half/i
+      @scope = @scope/base
+      base/2
+    when /quarter/i
+      @scope = @scope/base
+      base/4
+    when /other/i
+      2
+    else
+      @interval
+    end
+  end
+  
+  def calc_precision(scope = nil)
+    @at = 0 if scope
+    
+    case scope || @scope
+    when 1.minute
+      unless @next_run.sec == @at
+        @next_run += (@at - @next_run.sec)
+      end
+    when 1.hour
+      unless @next_run.min == @at
+        @next_run += (@at - @next_run.min).minutes
+      end
+      calc_precision 1.minute
+    when 1.day
+      unless @next_run.hour == @at
+        @next_run += (@at - @next_run.hour).hours
+      end
+      calc_precision 1.hour
+    when 1.week
+      unless @next_run.hour == @at
+        @next_run += (@at - @next_run.hour).hours
+      end
+      calc_precision 1.hour
+    end
+  end
+  
+  def calc_limits
+    if @from or @to
+      now = case @scope
+      when 1.second
+        @next_run.sec
+      when 1.minute
+        @next_run.min
+      when 1.hour
+        @next_run.hour
+      when 1.day
+        @next_run.day
+      end
+      
+      if @from and now < @from
+        @next_run += (@from - now) * @scope
+      elsif @to and now > @to
+        @next_run += ((@from || 0) - now) * @scope + uptime
+      end
+    end
+  end
+  
+  def uptime
+    case @scope
+    when 1.second
+      1.minute
+    when 1.minute
+      1.hour
+    when 1.hour
+      1.day
+    when 1.day
+      days_of_month.days
+    when 1.week
+      days_of_month.days
+    end
+  end
+  
+  def downtime
+    case @scope
+    when 1.minute
+      1.second
+    when 1.hour
+      1.minute
+    when 1.day
+      1.hour
+    when 1.week
+      1.hour
+    end
+  end
+  
+  def days_of_month
+    (Date.new(Time.now.year, 12, 31).to_date << (12 - @last_run.month)).day
+  end
+end

data/script/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# File: script/console
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs =  " -r irb/completion"
+# Perhaps use a console_lib to store any extra methods I may want available in the cosole
+# libs << " -r #{File.dirname(__FILE__) + '/../lib/console_lib/console_logger.rb'}"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/periodicity.rb'}"
+puts "Loading periodicity gem"
+exec "#{irb} #{libs} --simple-prompt"

data/script/destroy

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/destroy'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Destroy.new.run(ARGV)

data/script/generate

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/generate'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Generate.new.run(ARGV)

data/spec/periodicity_spec.rb

@@ -0,0 +1,94 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe Period do
+  it "should return now if not run before" do
+    Period.new.next_run.to_i.should == Time.now.to_i
+  end
+  
+  it "should raise when period not set properly" do
+    lambda {Period.new(Time.now).next_run}.should raise_error
+    lambda {Period.new(Time.now).every(12).next_run}.should raise_error
+    lambda {Period.new(Time.now).minutes.next_run}.should raise_error
+  end
+  
+  it "should return correct time on simple stuff" do
+    period.every(3).weeks.next_run.should == "Aug 26 00:00:00 2009".to_time
+    period.every(4).days.next_run.should == "Aug 09 00:00:00 2009".to_time
+    period.every(2).hours.next_run.should == "Aug 05 16:00:00 2009".to_time
+    period.every(30).minutes.next_run.should == "Aug 05 15:10:00 2009".to_time
+  end
+  
+  it "should return correct time on a little bit more complex stuff" do
+    period.every.day.next_run.should == "Aug 06 00:00:00 2009".to_time
+    period.every(:quarter).hour.next_run.should == "Aug 05 14:55:00 2009".to_time
+    period.every(:half).minute.next_run.should == "Aug 05 14:40:53 2009".to_time
+    period.every(:other).hour.next_run.should == period.every(2).hours.next_run
+
+    period.every.day.at(:morning).next_run.should == "Aug 06 09:00:00 2009".to_time
+    period.every.day.at(:noon).next_run.should == "Aug 06 12:00:00 2009".to_time
+    period.every.day.at(:afternoon).next_run.should == "Aug 06 19:00:00 2009".to_time
+    
+    period.every.day.at(:midnight).next_run.should == "Aug 06 00:00:00 2009".to_time
+    period.every.day.at(:midnight).next_run(1).should == "Aug 07 00:00:00 2009".to_time
+    period.every.day.at(:midnight).next_run(2).should == "Aug 08 00:00:00 2009".to_time
+
+    period.every.day.at('5').next_run.should == "Aug 06 05:00:00 2009".to_time
+    period.every.day.at('5:00').next_run.should == "Aug 06 05:00:00 2009".to_time
+    period.every.day.at('05:00').next_run.should == "Aug 06 05:00:00 2009".to_time
+    
+    lambda {period.every.day.at('05:30').next_run}.should raise_error # not yet implemented
+  end
+  
+  it "should return correct time with precision" do
+    period.every.week.at(20).next_run.should == "Aug 12 20:00:00 2009".to_time
+    period.every.day.at(14).next_run.should == "Aug 06 14:00:00 2009".to_time
+    
+    period.every.hour.at(30).next_run.should == "Aug 05 15:30:00 2009".to_time
+    period.every.hour.at(30).next_run(1).should == "Aug 05 16:30:00 2009".to_time
+    period.every.hour.at(30).next_run(2).should == "Aug 05 17:30:00 2009".to_time
+  end
+  
+  it "should take into account the limits" do
+    period.every(2).hours.from(18).next_run.should == "Aug 05 18:00:00 2009".to_time
+    period.every.hour.from(13).next_run.should == "Aug 05 15:00:00 2009".to_time
+    period.every(2).hours.from(12).next_run.should == "Aug 05 16:00:00 2009".to_time
+    
+    period.every(2).hours.from(21).next_run.should == "Aug 05 21:00:00 2009".to_time
+    period.every(2).hours.from(21).next_run(1).should == "Aug 05 23:00:00 2009".to_time
+    period.every(2).hours.from(21).next_run(2).should == "Aug 06 21:00:00 2009".to_time
+    
+    period.every(2).hours.to(12).next_run.should == "Aug 06 00:00:00 2009".to_time
+    period.every(2).hours.to(12).next_run(1).should == "Aug 06 02:00:00 2009".to_time
+    period.every(2).hours.to(12).next_run(2).should == "Aug 06 04:00:00 2009".to_time
+    
+    period.every(5).minutes.from(15).to(50).next_run(0).should == "Aug 05 14:45:00 2009".to_time
+    period.every(5).minutes.from(15).to(50).next_run(1).should == "Aug 05 14:50:00 2009".to_time
+    period.every(5).minutes.from(15).to(50).next_run(2).should == "Aug 05 15:15:00 2009".to_time
+    # period.every(5).minutes.from(15).to(50).next_run(3).should == "Aug 05 15:20:00 2009".to_time # skip has limits...
+
+    period.every(2).hours.from(8).to(12).next_run(0).should == "Aug 06 08:00:00 2009".to_time
+    period.every(2).hours.from(8).to(12).next_run(1).should == "Aug 06 10:00:00 2009".to_time
+    period.every(2).hours.from(8).to(12).next_run(2).should == "Aug 06 12:00:00 2009".to_time
+    period.every(2).hours.from(8).to(12).next_run(3).should == "Aug 07 08:00:00 2009".to_time
+    # period.every(2).hours.from(8).to(12).next_run(4).should == "Aug 07 10:00:00 2009".to_time # skip has limits...
+
+    period.every(3).days.from(5).to(20).next_run(0).should == "Aug 08 00:00:00 2009".to_time
+    period.every(3).days.from(5).to(20).next_run(1).should == "Aug 11 00:00:00 2009".to_time
+    period.every(3).days.from(5).to(20).next_run(2).should == "Aug 14 00:00:00 2009".to_time
+    period.every(3).days.from(5).to(20).next_run(3).should == "Aug 17 00:00:00 2009".to_time
+    period.every(3).days.from(5).to(20).next_run(4).should == "Aug 20 00:00:00 2009".to_time
+    period.every(3).days.from(5).to(20).next_run(5).should == "Sep 05 00:00:00 2009".to_time
+  end
+  
+  it "should avoid some pitfalls" do
+    Period.new("Aug 05 14:41:23 2009".to_time).every.hour.at(40).next_run.should == "Aug 05 15:40:00 2009".to_time
+    Period.new("Aug 05 14:39:23 2009".to_time).every.hour.at(40).next_run.should == "Aug 05 15:40:00 2009".to_time
+    
+    lambda {period.from(5).to(1)}.should raise_error
+    lambda {period.to(1).from(5)}.should raise_error
+  end
+  
+  def period
+    return Period.new("Aug 05 14:40:23 2009".to_time)
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--colour

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems' unless ENV['NO_RUBYGEMS']
+  gem 'rspec'
+  require 'spec'
+end
+
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require 'periodicity'

data/tasks/rspec.rake

@@ -0,0 +1,21 @@
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems' unless ENV['NO_RUBYGEMS']
+  require 'spec'
+end
+begin
+  require 'spec/rake/spectask'
+rescue LoadError
+  puts <<-EOS
+To use rspec for testing you must install rspec gem:
+    gem install rspec
+EOS
+  exit(0)
+end
+
+desc "Run the specs under spec/models"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ['--options', "spec/spec.opts"]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: vrinek-periodicity
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Kostas Karachalios
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-06 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.3.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.3.2
+    version: 
+description: Helps calculate the next run for schedulers using a human readable syntax.
+email: 
+- kostas.karachalios@me.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- PostInstall.txt
+- README.rdoc
+files: 
+- History.txt
+- Manifest.txt
+- PostInstall.txt
+- README.rdoc
+- Rakefile
+- lib/periodicity.rb
+- lib/periodicity/period.rb
+- script/console
+- script/destroy
+- script/generate
+- spec/periodicity_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- tasks/rspec.rake
+has_rdoc: false
+homepage: http://github.com/vrinek/periodicity
+licenses: 
+post_install_message: PostInstall.txt
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: periodicity
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Helps calculate the next run for schedulers using a human readable syntax.
+test_files: []
+