timetastic 0.1.1

data/lib/timetastic.rb

@@ -0,0 +1,133 @@
+require 'date'
+require 'time'
+
+module Timetastic
+  Domains = [ :hours, :weeks, :days, :months, :years ]
+
+  class << self
+    attr_accessor :fixed_time # see Timetastic#fixate() below
+
+    def last(delta = 1, relative_to = nil)
+      Traveller.new(-1, delta, relative_to)
+    end
+
+    alias_method :past, :last
+
+    def next(delta = 1, relative_to = nil)
+      Traveller.new(1, delta, relative_to)
+    end
+
+    alias_method :coming, :next
+
+    # Fixes the relative time by which all of Timetastic operations
+    # are carried out for the duration of the given block.
+    #
+    # Mainly used for tests and gem development.
+    #
+    # An alternative way to 'fix' the time is to directly use the exposed
+    # attribute Timetastic#fixed_time, ie:
+    #
+    # => Timetastic.fixed_time = Time.new(Time.now.year, 6, 1)
+    #
+    # You can simply set the attribute to nil to reset the time back to Time.now
+    def fixate(y, m = 1, d = 1, h = 0, mi = 0, s = 0, &block)
+      if y.is_a?(Time)
+        @fixed_time = y
+      else
+        @fixed_time = Time.new(y,m,d,h,mi,s)
+      end
+      block.call(@fixed_time)
+      @fixed_time = nil
+    end
+
+    # Snippet that calculates the number of days in any given month
+    # taking into account leap years.
+    #
+    # Credit goes to this SO thread: bit.ly/4GjMor
+    def days_in_month(year, month)
+      (Date.new(year, 12, 31) << (12-month)).day
+    end
+
+    # Returns the relative time by which operations are carried out
+    def now()
+      @fixed_time || Time.now
+    end
+  end
+
+  private
+
+  class Traveller
+    attr_reader :direction, :distance
+
+    def initialize(direction, distance, relative_to = nil)
+      @distance = distance.to_i
+      @relative_to = relative_to
+      @direction = case direction
+      when -1; :ago
+      when  1; :hence
+      end
+    end
+
+    Domains.each { |domain|
+      define_method(domain) { relative_anchored_time(domain) }
+      alias_method :"#{domain[0..-2]}", domain
+    }
+
+    protected
+
+    def relative_anchored_time(domain)
+      t = @distance.send(domain).send(@direction, @relative_to)
+
+      case domain
+      when :days, :weeks;
+        Time.new(t.year, t.month, t.day)
+      when :months; Time.new(t.year, t.month, 1)
+      when :years;  Time.new(t.year, 1, 1)
+      end
+    end
+  end # Timetastic::Traveller
+
+end # end of Module#Timetastic
+
+class Fixnum
+  Timetastic::Domains.each do |domain|
+    define_method(domain) { @time_offset_domain = domain; self }
+
+    # an alias for the singular version of the domain
+    alias_method :"#{domain[0..-2]}", domain
+  end
+
+  def ago(relative_to = nil)
+    relative_time(-1, relative_to)
+  end
+
+  def hence(relative_to = nil)
+    relative_time(1, relative_to)
+  end
+
+  alias_method :ahead, :hence
+  alias_method :from_now, :hence
+
+  protected
+
+  attr_reader :time_offset_domain
+
+  def relative_time(coef, relative_to = nil)
+    d = (coef.to_i) / (coef.to_i.abs) * self # delta
+    n = relative_to || Timetastic.now
+
+    case @time_offset_domain
+    when :hours
+      Time.at(n.to_i + d * 3600)
+    when :days
+      Time.at(n.to_i + d * 86400)
+    when :weeks
+      Time.at(n.to_i + d * 604800)
+    when :months
+      Time.at(n.to_i + d * 2592000)
+    when :years
+      Time.new(n.year + d, n.month, n.day, n.hour, n.min, n.sec)
+    end
+  end
+
+end

data/spec/timetastic_spec.rb

@@ -0,0 +1,320 @@
+describe Timetastic do
+  tt = Timetastic # alias it to reduce clutter
+
+  before do
+  end
+
+  after do
+  end
+
+  describe "Past features" do
+
+    it "should locate the last year from today" do
+      tt.fixate(2012, 8, 1) { |t|
+        1.year.ago.should == Time.new(2011, 8, 1)
+      }
+    end
+
+    it "should locate the last month from today" do
+      tt.fixate(2012, 12, 26) { |t|
+        1.month.ago.should == Time.new(2012, 11, 26)
+      }
+    end
+
+    it "should locate the last week from today" do
+      tt.fixate(2012, 12, 26) {
+        1.week.ago.should == Time.new(2012, 12, 19)
+      }
+    end
+
+    it "should locate the last day from today" do
+      tt.fixate(2012, 12, 26) {
+        1.day.ago.should == Time.new(2012, 12, 25)
+      }
+    end
+
+    it "should locate the last hour from now" do
+      tt.fixate(2012, 12, 26, 14) {
+        1.hour.ago.should == Time.new(2012, 12, 26, 13)
+        12.hours.ago.should == Time.new(2012, 12, 26, 2)
+      }
+    end
+
+  end # Past locators
+
+  describe "Future locators" do
+    it "should locate the coming year from today" do
+      tt.fixate(2012, 12, 26) {
+        1.year.hence.should == Time.new(2013, 12, 26)
+      }
+    end
+
+    it "should locate the coming month from today" do
+      tt.fixate(2012, 10, 26) {
+        1.month.hence.should == Time.new(2012, 11, 25)
+      }
+    end
+
+    it "should locate the coming week from today" do
+      tt.fixate(2012, 12, 20) {
+        1.week.ahead.should == Time.new(2012, 12, 27)
+      }
+    end
+
+    it "should locate the coming day from today" do
+      tt.fixate(2012, 12, 26) {
+        1.day.hence.should == Time.new(2012, 12, 27)
+      }
+    end
+
+  end # Future locators
+
+  describe "Anchored past locators" do
+    it "should point to the start of last year" do
+      tt.fixate(2012, 3, 3, 5, 32, 16) {
+        tt.last.year.should == Time.new(2011, 1, 1)
+      }
+    end
+
+    it "should point to the start of last month" do
+      tt.fixate(2012, 4, 16, 5, 32, 16) {
+        tt.last.month.should == Time.new(2012, 3, 1)
+      }
+    end
+
+    it "should point to the start of last day" do
+      tt.fixate(2012, 4, 16, 5, 32, 16) {
+        tt.last.day.should == Time.new(2012, 4, 15)
+      }
+    end
+
+    it "should point to the start of the year before last year" do
+      tt.fixate(2012, 4, 16, 5, 32, 16) {
+        tt.last(2).years.should == Time.new(2010, 1, 1)
+      }
+    end
+
+    it "should point to the start of the month before last month" do
+      tt.fixate(2012, 4, 16, 5, 32, 16) {
+        tt.last(2).months.should == Time.new(2012, 2, 1)
+      }
+    end
+
+    it "should point to the start of the day before last day" do
+      tt.fixate(2012, 4, 16, 5, 32, 16) {
+        tt.last(2).days.should == Time.new(2012, 4, 14)
+      }
+    end
+  end # Anchored past locators
+
+  describe "Anchored future locators" do
+    it "should point to the start of next year" do
+      tt.fixate(2012, 4, 16, 5, 32, 16) {
+        tt.next.year.should == Time.new(2013, 1, 1)
+      }
+    end
+
+    it "should point to the start of next month" do
+      tt.fixate(2012, 4, 16, 5, 32, 16) {
+        tt.next.month.should == Time.new(2012, 5, 1)
+      }
+    end
+
+    it "should point to the start of next day" do
+      tt.fixate(2012, 4, 16, 5, 32, 16) {
+        tt.next.day.should == Time.new(2012, 4, 17)
+      }
+    end
+
+    it "should point to the start of the year after the coming year" do
+      tt.fixate(2012, 4, 16, 5, 32, 16) {
+        tt.next(2).years.should == Time.new(2014, 1, 1)
+      }
+    end
+
+    it "should point to the start of the month after the coming month" do
+      tt.fixate(2012, 4, 16, 5, 32, 16) {
+        tt.next(2).months.should == Time.new(2012, 6, 1)
+      }
+    end
+
+    it "should point to the start of the day after tomorrow" do
+      tt.fixate(2012, 4, 16, 5, 32, 16) {
+        tt.next(2).days.should == Time.new(2012, 4, 18)
+      }
+    end
+  end # Anchored future locators
+
+  describe "Forward wrapping" do
+
+    it "should wrap forward a day to locate the hour" do
+      tt.fixate(2012, 6, 26, 21) {
+        # this shouldn't wrap
+        1.hour.ahead.should == Time.new(2012, 6, 26, 22)
+        # but this should
+        4.hour.ahead.should == Time.new(2012, 6, 27, 1)
+      }
+    end
+
+    it "should wrap forward a month to locate the day" do
+      tt.fixate(2012, 6, 29) {
+        # this should wrap
+        4.days.ahead.should == Time.new(2012, 7, 3)
+        # and this shouldn't
+        1.days.ahead.should == Time.new(2012, 6, 30)
+      }
+    end
+
+    # we know that 2011 is a leap (gregorian) year, and 2012 isn't
+    # nr of days in february in a leap year is 28, otherwise it's 29
+    it "should wrap forward a month to locate the day in a leap year" do
+      tt.fixate(2011, 2, 28) {
+        2.days.ahead.should   == Time.new(2011, 3, 2)
+        1.days.ahead.should   == Time.new(2011, 3, 1)
+        0.days.ahead.should   == Time.new(2011, 2, 28)
+        -1.days.ahead.should  == Time.new(2011, 2, 27)
+      }
+    end
+
+    it "should wrap forward a month to locate the week" do
+      tt.fixate(2012, 6, 20) {
+        # shouldn't wrap
+        1.week.ahead.should == Time.new(2012, 6, 27)
+        # this should wrap
+        2.weeks.ahead.should == Time.new(2012, 7, 4)
+      }
+
+
+      # february has 29 on non-leap
+      tt.fixate(2012, 2, 22) {
+        1.week.ahead.should == Time.new(2012, 2, 29)
+      }
+
+      # 28 on leap year
+      tt.fixate(2011, 2, 22) {
+        1.week.ahead.should == Time.new(2011, 3, 1)
+      }
+    end
+
+    it "should wrap forward a year to locate a month" do
+      tt.fixate(2011, 12, 5) {
+        1.month.ahead.should == Time.new(2012, 1, 4)
+      }
+    end
+  end # Forward wrapping
+
+  describe "Backwards wrapping" do
+    it "should wrap backwards a day to locate the hour" do
+      tt.fixate(2012, 6, 26, 1) {
+        # this shouldn't wrap
+        1.hour.ago.should == Time.new(2012, 6, 26, 0)
+        # but these should
+        2.hours.ago.should == Time.new(2012, 6, 25, 23)
+        4.hour.ago.should == Time.new(2012, 6, 25, 21)
+      }
+    end
+
+    it "should wrap backwards a month to locate the day" do
+      tt.fixate(2012, 3, 2) {
+        4.days.ago.should == Time.new(2012, 2, 27)
+        2.days.ago.should == Time.new(2012, 2, 29)
+        tt.last(2).days.should == Time.new(2012, 2, 29)
+        tt.last(4).days.should == Time.new(2012, 2, 27)
+      }
+    end
+
+    it "should wrap backwards a month to locate the day in a leap year" do
+      tt.fixate(2011, 3, 2) {
+        2.days.ago.should == Time.new(2011, 2, 28)
+        4.days.ago.should == Time.new(2011, 2, 26)
+        tt.last(2).days.should == Time.new(2011, 2, 28)
+        tt.last(4).days.should == Time.new(2011, 2, 26)
+      }
+    end
+
+    it "should wrap backwards more than a month to locate a day" do
+      Timetastic.fixate(2012, 6, 15) {
+        2.days.ago.should == Time.new(2012, 6, 13)
+        15.days.ago.should == Time.new(2012, 5, 31)
+        17.days.ago.should == Time.new(2012, 5, 29)
+      }
+      Timetastic.fixate(2012, 6, 10) {
+        29.days.ago.should == Time.new(2012, 5, 12)
+        30.days.ago.should == Time.new(2012, 5, 11)
+        32.days.ago.should == Time.new(2012, 5, 9)
+        64.days.ago.should == Time.new(2012, 4, 7)
+      }
+    end
+
+    it "should wrap backwards a month to locate the week" do
+      tt.fixate(2012, 6, 8) {
+        1.week.ago.should == Time.new(2012, 6, 1)
+        # this should wrap
+        2.weeks.ago.should == Time.new(2012, 5, 25)
+        tt.last(2).weeks.should == Time.new(2012, 5, 25)
+      }
+    end
+
+    it "should wrap backwards a year to locate a month" do
+      tt.fixate(2011, 3, 5) {
+        # this should wrap
+        6.month.ago.should == Time.new(2010, 9, 6, 1)
+        3.month.ago.should == Time.new(2010, 12, 5)
+        # these shouldn't
+        1.month.ago.should == Time.new(2011, 2, 3)
+        2.month.ago.should == Time.new(2011, 1, 4)
+      }
+    end
+
+  end # Backwards wrapping
+
+  describe "Far-off, OOR wrapping" do
+    it "should wrap backwards more than a year to locate a month" do
+      Timetastic.fixate(2012, 6, 1) {
+        10.months.ago.should == Time.new(2011, 8, 6)
+        12.months.ago.should == Time.new(2011, 6, 7)
+        13.months.ago.should == Time.new(2011, 5, 8)
+        18.months.ago.should == Time.new(2010, 12, 8, 23)
+        20.months.ago.should == Time.new(2010, 10, 10)
+        36.months.ago.should == Time.new(2009, 6, 17)
+        48.months.ago.should == Time.new(2008, 6, 22)
+        60.months.ago.should == Time.new(2007, 6, 28)
+        66.months.ago.should == Time.new(2006, 12, 29, 23)
+      }
+
+      Timetastic.fixate(2007, 8, 15) { |t|
+        8.months.ago.should == Time.new(2006,12,17, 23)
+        19.months.ago.should == Time.new(2006,1,21, 23)
+        20.months.ago.should == Time.new(2005,12,22, 23)
+      }
+    end
+
+    it "should wrap forward more than a month to locate a day" do
+      Timetastic.fixate(2012, 6, 15) {
+        32.days.ahead.should == Time.new(2012, 7, 17)
+        64.days.ahead.should == Time.new(2012, 8, 18)
+        65.days.ahead.should == Time.new(2012, 8, 19)
+        15.days.ahead.should == Time.new(2012, 6, 30)
+        16.days.ahead.should == Time.new(2012, 7, 1)
+        90.days.ahead.should == Time.new(2012, 9, 13)
+        365.days.ahead.should == Time.new(2013, 6, 15)
+        2700.days.ahead.should == Time.new(2019, 11, 5, 23)
+      }
+    end
+
+    it "should wrap forwards more than a year to locate a month" do
+      Timetastic.fixate(2012, 6, 1) {
+        6.months.ahead.should == Time.new(2012, 11, 28)
+        18.months.ahead.should == Time.new(2013, 11, 22, 23)
+        23.months.ahead.should == Time.new(2014, 4, 22)
+      }
+
+      Timetastic.fixate(2020, 7, 30) {
+        1.months.ahead.should == Time.new(2020, 8, 29)
+        14.months.ahead.should == Time.new(2021, 9, 23)
+        25.months.ahead.should == Time.new(2022, 8, 19)
+      }
+    end
+  end
+
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: timetastic
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
+platform: ruby
+authors:
+- Ahmad Amireh
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Pure Ruby date selection using an easy and readable interface. Calculation
+  of dates accounts for wrapping across days, months, and years.
+email: ahmad@algollabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/timetastic.rb
+- spec/timetastic_spec.rb
+homepage: https://github.com/amireh/timetastic
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Utility collection of relative date selectors similar to ActiveRecord's.
+test_files:
+- spec/timetastic_spec.rb