timeframe 0.1.0 → 0.1.1

data/.document

@@ -1,5 +1,5 @@
-README.rdoc
-lib/**/*.rb
-bin/*
-features/**/*.feature
-LICENSE
+README.markdown
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -15,7 +15,8 @@ tmtags
 
 ## PROJECT::GENERAL
 coverage
-rdoc
+doc/
+.yardoc/
 pkg
 
 ## PROJECT::SPECIFIC

data/Gemfile

@@ -1,4 +1,8 @@
-source "http://rubygems.org"
+source :rubygems
 
-# Specify your gem's dependencies in timeframe.gemspec
 gemspec
+
+# development dependencies
+gem 'yard'
+gem 'minitest'
+gem 'rake'

data/LICENSE

@@ -1,20 +1,20 @@
-Copyright (c) 2009 Andy Rossmeissl
-
-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.
+Copyright (c) 2009 Andy Rossmeissl
+
+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.markdown

@@ -0,0 +1,42 @@
+# timeframe
+
+A Ruby class for describing and interacting with timeframes.
+
+## Based on ISO 8601
+
+As [documented by wikipedia](http://en.wikipedia.org/wiki/ISO_8601#Time_intervals), time intervals are like:
+
+1. Start and end, such as `2007-03-01T13:00:00Z/2008-05-11T15:30:00Z`
+2. Start and duration, such as `2007-03-01T13:00:00Z/P1Y2M10DT2H30M`
+3. Duration and end, such as `P1Y2M10DT2H30M/2008-05-11T15:30:00Z`
+4. Duration only, such as `P1Y2M10DT2H30M`, with additional context information [not supported]
+
+or more simply
+
+    <start>/<end>
+    <start>/<duration>
+    <duration>/<end>
+    <duration> [not supported]
+
+## Precision
+
+Currently the end result is precise to 1 day, so these are the same:
+
+* `2007-03-01T00:00:00Z/2008-05-11T00:00:00Z`
+* `2007-03-01/2008-05-11`
+
+This may change in the future.
+
+## Documentation
+
+http://rdoc.info/projects/rossmeissl/timeframe
+
+## Acknowledgements
+
+The good parts of Timeframe all came from the gentlemen at Fingertips[http://fngtps.com].
+
+Thanks to @artemk for https://github.com/rossmeissl/timeframe/pull/5
+
+## Copyright
+
+Copyright (c) 2012 Andy Rossmeissl, Seamus Abshere

data/Rakefile

@@ -1,8 +1,3 @@
-# must be included before rubygems or bundler
-if ENV['TIMEFRAME_HOME_RUN'] == 'true'
-  require 'home_run'
-end
-
 require 'bundler'
 Bundler::GemHelper.install_tasks
 
@@ -17,10 +12,5 @@ end
 
 task :default => :test
 
-require 'rdoc/task'
-RDoc::Task.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "timeframe"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+require 'yard'
+YARD::Rake::YardocTask.new

data/lib/timeframe.rb

@@ -3,6 +3,8 @@ require 'multi_json'
 require 'active_support/version'
 require 'active_support/core_ext' if ActiveSupport::VERSION::MAJOR >= 3
 
+require 'timeframe/iso_8601'
+
 # Encapsulates a timeframe between two dates. The dates provided to the class are always until the last date. That means
 # that the last date is excluded.
 #
@@ -43,8 +45,14 @@ class Timeframe
     # Construct a new Timeframe by parsing an ISO 8601 time interval string
     # http://en.wikipedia.org/wiki/ISO_8601#Time_intervals
     def from_iso8601(str)
-      raise ArgumentError, 'Intervals should be specified according to ISO 8601, method 1, eliding times' unless str =~ /^\d\d\d\d-\d\d-\d\d\/\d\d\d\d-\d\d-\d\d$/
-      new *str.split('/')
+      delimiter = str.include?('/') ? '/' : '--'
+      a_raw, b_raw = str.split delimiter
+      if a_raw.blank? or b_raw.blank?
+        raise ArgumentError, "Interval must be specified according to ISO 8601 <start>/<end>, <start>/<duration>, or <duration>/<end>."
+      end
+      a = Iso8601::A.new a_raw
+      b = Iso8601::B.new b_raw
+      new a.to_time(b), b.to_time(a)
     end
     
     # Construct a new Timeframe from a hash with keys startDate and endDate    
@@ -68,14 +76,14 @@ class Timeframe
       when ::String
         str = input.strip
         if str.start_with?('{')
-          from_hash ::MultiJson.decode(str)
+          from_hash MultiJson.decode(str)
         elsif input =~ /\A\d\d\d\d\z/
           from_year input
         else
           from_iso8601 str
         end
       else
-        raise ::ArgumentError, "Must be String or Hash"
+        raise ArgumentError, "Must be String or Hash"
       end
     end
     alias :interval :parse
@@ -256,7 +264,7 @@ class Timeframe
     b = timeframes.collect(&:start_date) + [ end_date ]
 
     a.zip(b).map do |gap|
-      Timeframe.new(*gap, :skip_year_boundary_crossing_check => true) if gap[1] > gap[0]
+      Timeframe.new(*gap) if gap[1] > gap[0]
     end.compact
   end
 
@@ -284,7 +292,27 @@ class Timeframe
   end
   alias :to_s :iso8601
   alias :to_param :iso8601
-
+  
+  def dates
+    dates = []
+    cursor = start_date
+    while cursor < end_date
+      dates << cursor
+      cursor = cursor.succ
+    end
+    dates
+  end
+  
+  def first_days_of_months
+    dates = []
+    cursor = start_date.beginning_of_month
+    while cursor < end_date
+      dates << cursor
+      cursor = cursor >> 1
+    end
+    dates
+  end
+  
   # Deprecated
   def from # :nodoc:
     @start_date

data/lib/timeframe/iso_8601.rb

@@ -0,0 +1,93 @@
+class Timeframe
+  module Iso8601
+    # Internal use.
+    #
+    # Parses a duration like 'P1Y2M4DT3H4M2S'
+    class Duration < ::Struct.new(:date_part, :time_part)
+      def seconds
+        (y*31_556_926 + m*2_629_743.83 + d*86_400 + h*3_600 + minutes*60 + s).ceil
+      end
+      private
+      def y;        @y       ||= parse(date_part, :Y); end
+      def m;        @m       ||= parse(date_part, :M); end
+      def d;        @d       ||= parse(date_part, :D); end
+      def h;        @h       ||= parse(time_part, :H); end
+      def minutes;  @minutes ||= parse(time_part, :M); end
+      def s;        @s       ||= parse(time_part, :S); end
+      def parse(part, indicator)
+        if part =~ /(\d+)#{indicator.to_s}/
+          $1.to_f
+        else
+          0
+        end
+      end
+    end
+
+    # Internal use.
+    class Side
+      # We add one day because so that it can be excluded per timeframe's conventions.
+      EXCLUDED_LAST_DAY = 86_400
+      attr_reader :date_part, :time_part
+      def to_time(counterpart)
+        if date_part.start_with?('P')
+          counterpart.resolve_time(self) + resolve_offset + EXCLUDED_LAST_DAY
+        else
+          resolve_time counterpart
+        end
+      end
+    end
+    
+    # Internal use.
+    #
+    # The "A" side of "A/B"
+    class A < Side
+      def initialize(raw)
+        raw = raw.upcase
+        @date_part, @time_part = raw.split('T')
+        @time_part ||= ''
+      end
+      def resolve_time(*)
+        Time.parse [date_part, time_part].join('T')
+      end
+      # When A is a period, it counts as a negative offset to B.
+      def resolve_offset
+        0.0 - Duration.new(date_part, time_part).seconds
+      end
+    end
+    
+    # Internal use.
+    #
+    # The "B" side of "A/B"
+    class B < Side
+      def initialize(raw)
+        raw = raw.upcase
+        if raw.include?(':') and not raw.include?('T')
+          # it's just a shorthand for time
+          @date_part = ''
+          @time_part = raw
+        else
+          @date_part, @time_part = raw.split('T')
+          @time_part ||= ''
+        end
+      end
+      # When shorthand is used, we need to peek at our counterpart (A) in order to steal letters
+      # Shorthand can only be used on the B side, and only in <start>/<end> format.
+      def resolve_time(counterpart)
+        filled_in_date_part = unless date_part.count('-') == 2
+          counterpart.date_part[0..(0-date_part.length-1)] + date_part
+        else
+          date_part
+        end
+        filled_in_time_part = if time_part.count(':') < 2
+          counterpart.time_part[0..(0-time_part.length-1)] + time_part
+        else
+          time_part
+        end
+        Time.parse [filled_in_date_part, filled_in_time_part].join('T')
+      end
+      def resolve_offset
+        Duration.new(date_part, time_part).seconds
+      end
+    end
+  end
+end

data/lib/timeframe/version.rb

@@ -1,3 +1,3 @@
 class Timeframe
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/spec/timeframe_spec.rb

@@ -59,7 +59,7 @@ describe Timeframe do
     end
   end
 
-  describe '.constrained_new' do
+  describe :constrained_new do
     let(:start) { Date.parse('2008-02-14') }
     let(:finish) { Date.parse('2008-05-10') }
     let(:constraint_start) { Date.parse('2008-01-01') }
@@ -108,7 +108,7 @@ describe Timeframe do
     end
   end
 
-  describe '.this_year' do
+  describe :this_year do
     it "should return the current year" do
       Timeframe.this_year.must_equal Timeframe.new(:year => Time.now.year)
     end
@@ -190,7 +190,7 @@ describe Timeframe do
 
   describe '#/' do
     it "should return a fraction of another timeframe" do 
-      (Timeframe.new(:month => 4, :year => 2009) / Timeframe.new(:year => 2009)).must_equal (30.0 / 365.0)
+      (Timeframe.new(:month => 4, :year => 2009) / Timeframe.new(:year => 2009)).must_equal(30.0 / 365.0)
     end
   end
 
@@ -224,10 +224,50 @@ describe Timeframe do
     end
   end
   
-  describe '.parse' do
-    it 'understands ISO8601' do
-      Timeframe.parse('2009-01-01/2010-01-01').must_equal Timeframe.new(:year => 2009)
+  describe :parse do
+    describe 'ISO 8601 <start>/<end>' do
+      it 'works without time' do
+        Timeframe.parse('2007-03-01/2008-05-11').must_equal Timeframe.new(Date.new(2007, 3, 1), Date.new(2008, 5, 11))
+        Timeframe.parse('2007-03-01--2008-05-11').must_equal Timeframe.new(Date.new(2007, 3, 1), Date.new(2008, 5, 11))
+      end
+      it 'works with time' do
+        Timeframe.parse('2007-03-01T13:00:00Z/2008-05-11T15:30:00Z').must_equal Timeframe.new(Date.new(2007, 3, 1), Date.new(2008, 5, 11))
+        Timeframe.parse('2007-03-01T13:00:00Z--2008-05-11T15:30:00Z').must_equal Timeframe.new(Date.new(2007, 3, 1), Date.new(2008, 5, 11))
+      end
+      it 'takes shorthand' do
+        Timeframe.parse('2007-11-13/15').must_equal Timeframe.new(Date.new(2007, 11, 13), Date.new(2007, 11, 15)) # "2007-11-13/15", i.e. from any time on 2007-11-13 to any time on 2007-11-15
+        Timeframe.parse("2008-02-15/03-14").must_equal Timeframe.new(Date.new(2008, 2, 15), Date.new(2008, 3, 14)) # "2008-02-15/2008-03-14"
+        Timeframe.parse("2007-12-14T13:30/15:30").must_equal Timeframe.new(Date.new(2007, 12, 14), Date.new(2007, 12, 14)) # "2007-12-14T13:30/2007-12-14T15:30".. imprecise!
+      end
+    end
+
+    describe 'ISO 8601 <start>/<duration>' do
+      it 'works without time' do
+        Timeframe.parse('2007-03-01/P1Y2M10DT2H30M').must_equal Timeframe.new(Date.new(2007, 3, 1), Date.new(2008, 5, 11))
+        Timeframe.parse('2007-03-01--P1Y2M10DT2H30M').must_equal Timeframe.new(Date.new(2007, 3, 1), Date.new(2008, 5, 11))
+      end
+      it 'works with time' do
+        Timeframe.parse('2007-03-01T13:00:00Z/P1Y2M10DT2H30M').must_equal Timeframe.new(Date.new(2007, 3, 1), Date.new(2008, 5, 11))
+        Timeframe.parse('2007-03-01T13:00:00Z--P1Y2M10DT2H30M').must_equal Timeframe.new(Date.new(2007, 3, 1), Date.new(2008, 5, 11))
+      end
+    end
+    
+    # note that 2008 was a leap year
+    describe 'ISO 8601 <duration>/<end>' do
+      it 'works with leap years' do
+        Timeframe.parse('2007-02-28--P1Y').must_equal Timeframe.new(Date.new(2007, 2, 28), Date.new(2008, 2, 29))
+        Timeframe.parse('P1Y--2008-02-29').must_equal Timeframe.new(Date.new(2007, 3, 1), Date.new(2008, 2, 29))
+      end
+      it 'works without time' do
+        Timeframe.parse('P1Y2M10DT2H30M/2008-05-11').must_equal Timeframe.new(Date.new(2007, 3, 2), Date.new(2008, 5, 11))
+        Timeframe.parse('P1Y2M10DT2H30M--2008-05-11').must_equal Timeframe.new(Date.new(2007, 3, 2), Date.new(2008, 5, 11))
+      end
+      it 'works with time' do
+        Timeframe.parse('P1Y2M10DT2H30M/2008-05-11T15:30:00Z').must_equal Timeframe.new(Date.new(2007, 3, 3), Date.new(2008, 5, 11))
+        Timeframe.parse('P1Y2M10DT2H30M--2008-05-11T15:30:00Z').must_equal Timeframe.new(Date.new(2007, 3, 3), Date.new(2008, 5, 11))
+      end
     end
+
     it 'understands plain year' do
       plain_year = 2009
       Timeframe.parse(plain_year).must_equal Timeframe.new(:year => plain_year)
@@ -271,6 +311,23 @@ EOS
       Timeframe.new(Date.parse('2008-01-01'), Date.parse('2010-01-01')).to_s.must_equal "2008-01-01/2010-01-01"
     end
   end
+  
+  describe '#dates' do
+    it "should enumerate all dates between start and end" do
+      dates = Timeframe.new(:year => 2008).dates
+      dates.min.must_equal Date.new(2008,1,1)
+      dates.max.must_equal Date.new(2008,12,31)
+      dates.uniq.length.must_equal 366
+      dates.select { |d| d.month == 2 }.length.must_equal 29
+    end
+  end
+  
+  describe '#first_days_of_months' do
+    it "should enumerate all the first days of included months" do
+      dates = Timeframe.parse('2011-05-01/2012-02-01').first_days_of_months
+      dates.must_equal [Date.new(2011,5,1), Date.new(2011,6,1), Date.new(2011,7,1), Date.new(2011,8,1), Date.new(2011,9,1), Date.new(2011,10,1), Date.new(2011,11,1), Date.new(2011,12,1), Date.new(2012,1,1)]
+    end
+  end
 
   describe "Array#multiple_timeframes_gaps_left_by" do
     it "should raise error if not a Timeframes are going to be merged" do

data/timeframe.gemspec

@@ -19,9 +19,6 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
   
-  s.add_development_dependency "minitest"
-  s.add_development_dependency 'home_run'
-  s.add_development_dependency 'rake'
   s.add_runtime_dependency 'activesupport', '>=2.3.5'
   s.add_runtime_dependency 'i18n'
   s.add_runtime_dependency 'multi_json'

metadata

@@ -1,165 +1,96 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: timeframe
-version: !ruby/object:Gem::Version 
-  hash: 27
+version: !ruby/object:Gem::Version
+  version: 0.1.1
   prerelease: 
-  segments: 
-  - 0
-  - 1
-  - 0
-  version: 0.1.0
 platform: ruby
-authors: 
+authors:
 - Andy Rossmeissl
 - Seamus Abshere
 - Derek Kastner
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-01-06 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: minitest
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  type: :development
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: home_run
-  prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rake
-  prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
+date: 2012-03-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: activesupport
-  prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: &2164797740 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 9
-        segments: 
-        - 2
-        - 3
-        - 5
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 2.3.5
   type: :runtime
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: i18n
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: *2164797740
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: &2164797080 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
-  name: multi_json
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  version_requirements: *2164797080
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: &2164796260 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id006
+  prerelease: false
+  version_requirements: *2164796260
 description: A Ruby class for describing and interacting with timeframes.
-email: 
+email:
 - andy@rossmeissl.net
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .document
 - .gitignore
 - Gemfile
 - LICENSE
-- README.rdoc
+- README.markdown
 - Rakefile
 - lib/timeframe.rb
 - lib/timeframe/core_ext/array.rb
+- lib/timeframe/iso_8601.rb
 - lib/timeframe/version.rb
 - spec/spec_helper.rb
 - spec/timeframe_spec.rb
 - timeframe.gemspec
 homepage: http://github.com/rossmeissl/timeframe
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: timeframe
-rubygems_version: 1.8.8
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
 summary: Date intervals
-test_files: []
-
+test_files:
+- spec/spec_helper.rb
+- spec/timeframe_spec.rb
 has_rdoc: 

data/README.rdoc

@@ -1,17 +0,0 @@
-= timeframe
-
-A Ruby class for describing and interacting with timeframes.
-
-== Documentation
-
-http://rdoc.info/projects/rossmeissl/timeframe
-
-== Acknowledgements
-
-The good parts of Timeframe all came from the gentlemen at Fingertips[http://fngtps.com].
-
-Thanks to @artemk for https://github.com/rossmeissl/timeframe/pull/5
-
-== Copyright
-
-Copyright (c) 2010 Andy Rossmeissl.