timespan 0.1.4 → 0.2.0

data/Gemfile

@@ -1,11 +1,14 @@
 source :rubygems
 
 gem 'chronic'
+gem 'chronic_duration'
 gem 'spanner'
-gem 'ruby-duration'
+gem 'ruby-duration', :git => 'git://github.com/kristianmandrup/ruby-duration.git'
 
 group :test, :development do
   gem "rspec", 		">= 2.8.0"
+  gem 'rails', 		'~> 3.2'
+  # gem 'i18n'
 end
 
 group :development do

data/Gemfile.lock

@@ -1,31 +1,88 @@
+GIT
+  remote: git://github.com/kristianmandrup/ruby-duration.git
+  revision: 002f43a5ad5b6191ae5ee218e532176005279384
+  specs:
+    ruby-duration (2.1.4)
+      activesupport (>= 3.0.0)
+      i18n
+
 GEM
   remote: http://rubygems.org/
   specs:
+    actionmailer (3.2.3)
+      actionpack (= 3.2.3)
+      mail (~> 2.4.4)
+    actionpack (3.2.3)
+      activemodel (= 3.2.3)
+      activesupport (= 3.2.3)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.1)
+      rack (~> 1.4.0)
+      rack-cache (~> 1.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.1.2)
     activemodel (3.2.3)
       activesupport (= 3.2.3)
       builder (~> 3.0.0)
+    activerecord (3.2.3)
+      activemodel (= 3.2.3)
+      activesupport (= 3.2.3)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activeresource (3.2.3)
+      activemodel (= 3.2.3)
+      activesupport (= 3.2.3)
     activesupport (3.2.3)
       i18n (~> 0.6)
       multi_json (~> 1.0)
-    bson (1.6.2)
+    arel (3.0.2)
     builder (3.0.0)
     chronic (0.6.7)
+    chronic_duration (0.9.6)
+      numerizer (~> 0.1.1)
     diff-lcs (1.1.3)
+    erubis (2.7.0)
     git (1.2.5)
+    hike (1.2.1)
     i18n (0.6.0)
     jeweler (1.8.3)
       bundler (~> 1.0)
       git (>= 1.2.5)
       rake
       rdoc
+    journey (1.0.3)
     json (1.6.6)
-    mongo (1.6.2)
-      bson (~> 1.6.2)
-    mongoid (2.4.9)
-      activemodel (~> 3.1)
-      mongo (~> 1.3)
-      tzinfo (~> 0.3.22)
+    mail (2.4.4)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.18)
     multi_json (1.3.2)
+    numerizer (0.1.1)
+    polyglot (0.3.3)
+    rack (1.4.1)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-ssl (1.3.2)
+      rack
+    rack-test (0.6.1)
+      rack (>= 1.0)
+    rails (3.2.3)
+      actionmailer (= 3.2.3)
+      actionpack (= 3.2.3)
+      activerecord (= 3.2.3)
+      activeresource (= 3.2.3)
+      activesupport (= 3.2.3)
+      bundler (~> 1.0)
+      railties (= 3.2.3)
+    railties (3.2.3)
+      actionpack (= 3.2.3)
+      activesupport (= 3.2.3)
+      rack-ssl (~> 1.3.2)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (~> 0.14.6)
     rake (0.9.2.2)
     rdoc (3.12)
       json (~> 1.4)
@@ -37,15 +94,20 @@ GEM
     rspec-expectations (2.9.1)
       diff-lcs (~> 1.1.3)
     rspec-mocks (2.9.0)
-    ruby-duration (2.1.3)
-      activesupport (>= 3.0.0)
-      i18n
-      mongoid (~> 2.4.0)
     simplecov (0.6.2)
       multi_json (~> 1.3)
       simplecov-html (~> 0.5.3)
     simplecov-html (0.5.3)
     spanner (0.0.2)
+    sprockets (2.1.2)
+      hike (~> 1.2)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    thor (0.14.6)
+    tilt (1.3.3)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
     tzinfo (0.3.33)
 
 PLATFORMS
@@ -54,9 +116,11 @@ PLATFORMS
 DEPENDENCIES
   bundler (>= 1.0.0)
   chronic
+  chronic_duration
   jeweler (>= 1.8.3)
+  rails (~> 3.2)
   rdoc (>= 3.12)
   rspec (>= 2.8.0)
-  ruby-duration
+  ruby-duration!
   simplecov (>= 0.5)
   spanner

data/README.md

@@ -1,30 +1,137 @@
 # Timespan
 
-Use TimeSpans in Ruby :)
+Use Timespans in Ruby :)
 
-Will calculate time diff in milliseconds between to dates, then allow you to get the time difference in some time unit as a number.
+Will calculate time diff between two dates, then allow you to get the time difference in some time unit as a number.
 
 ```ruby
-	t = TimeSpan.new(:start => Date.today, :duration => 3.days.ago)
+	t = Timespan.new(:start => Date.today, :duration => 3.days.ago)
 	t.to_days # => 3
 	t.to_weeks # => 0
 	t.to_secs # => 259200
 	t.to_hours = 10800
 
-	t = TimeSpan.new(:from => Date.today, :to => "6 weeks from now")	
+  t = Timespan.new("2 days") # from today
 
-	t = TimeSpan.new(:from => Date.today, :duration => "7 weeks 3 days")	
-	t = TimeSpan.new(:from => 2.days.ago, :duration => "5 months and 2 weeks")	
-``
+  t = Timespan.new("3 hrs").from(2.days.from_now)
+
+	t = Timespan.new(:from => Date.today, :to => "6 weeks from now")	
+
+	t = Timespan.new(:from => Date.today, :duration => "7 weeks 3 days")	
+	t = Timespan.new(:from => 2.days.ago, :duration => "5 months and 2 weeks")	
+```
 
 See specs for more examples of usage
 
-## TODO
+## Spanner
+
+Internally Timespan uses Spanner to parse duration strings.
+
+`Spanner.parse('23 hours 12 minutes')
+
+## Duration (ruby-duration)
+
+```ruby
+Duration.new(100) => #<Duration: minutes=1, seconds=40, total=100>
+Duration.new(:hours => 5, :minutes => 70) => #<Duration: hours=6, minutes=10, total=22200>
+
+Duration.new(:weeks => 3, :days => 1).format("%w %~w and %d %~d") => "3 weeks and 1 day"
+Duration.new(:weeks => 1, :days => 20).format("%w %~w and %d %~d") => "3 weeks and 6 days"
+```
+
+Duration locale file
+
+```yaml
+da:
+  ruby_duration:
+    second: sekond
+    seconds: sekonder
+    minute: minut
+    minutes: minutter
+    hour: time
+    hours: timer
+    day: dag
+    days: dage
+    week: uge
+    weeks: uges
+    month: måned
+    months: måneder
+    year: år
+    years: år
+```
+
+Duration datatype for Mongoid
+
+```ruby
+require 'duration/mongoid'
+
+class MyModel
+  include Mongoid::Document
+  field :duration, type => Duration
+end
+```
+
+## Timespan i18n
 
-* use Duration for duration calculations!
-* Calculate start_time and end_time based on duration if not set explicitly!
+Timespan locale file
+
+```yaml
+da:
+  timespan:
+    from: fra
+    to: til
+    lasting: der varer ialt
+```
+
+## Timespan for Mongoid
+
+Custom Timespan datatype
+
+```ruby
+require 'timespan/mongoid'
+
+class MyModel
+  include Mongoid::Document
+  field :period, type => Timespan
+end
+```
+
+## Chronic duration
+
+Is used to parse duration strings if Spanner can't be handle it
+
+`ChronicDuration.parse('4 minutes and 30 seconds')
+
+### Endure
+
+Use the 'endure' gem based on the old "days_and_times".
+
+See: [days_and_times](https://github.com/kristianmandrup/days_and_times)
+
+Currently it also uses Duration, which conflicts with the 'ruby-duration' gem.
+
+```
+  1.day #=> A duration of 1 day
+  7.days #=> A duration of 7 days
+  1.week #=> A duration of 1 week
+  1.week - 2.days #=> A duration of 5 days
+  1.week.from(Now()) #=> The time of 1 week from this moment
+  1.week.from(Today()) #=> The time of 1 week from the beginning of today
+  3.minutes.ago.until(7.minutes.from(Now())) #=> duration 3 minutes ago to 7 minutes from now
+  3.minutes.ago.until(7.minutes.from(Now())) - 2.minutes #=> duration 3 minutes ago to 5 minutes from now
+  4.weeks.from(2.days.from(Now())).until(8.weeks.from(Yesterday())) #=> A duration, starting in 4 weeks and 2 days, and ending 8 weeks from yesterday
+  1.week - 1.second #=> A duration of 6 days, 23 hours, 59 minutes, and 59 seconds
+  4.weeks / 2 #=> A duration of 2 weeks
+  4.weeks / 2.weeks #=> The integer 2
+  8.weeks.each {|week| ...} #=> Runs code for each week contained in the duration (of 8 weeks)
+  8.weeks.starting(Now()).each {|week| ...} #=> Runs code for each week in the duration, but each week is also anchored to a starting time, in sequence through the duration.
+  1.week.each {|week| ...} #=> Automatically chooses week as its iterator
+  7.days.each {|day| ...} #=> Automatically chooses day as its iterator
+  1.week.each_day {|day| ...} #=> Forcing the week to iterate through days
+  1.week.each(10.hours) {|ten_hour_segment| ...} #=> Using a custom iterator of 10 hours. There would be 17 of them, but notice that the last iteration will only be 8 hours.
+``
 
-## Contributing to timespan
+## Contributing to Timespan
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
@@ -34,7 +141,7 @@ See specs for more examples of usage
 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
 * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
 
-== Copyright
+## Copyright
 
 Copyright (c) 2012 Kristian Mandrup. See LICENSE.txt for
 further details.

data/Rakefile

@@ -17,8 +17,8 @@ Jeweler::Tasks.new do |gem|
   gem.name = "timespan"
   gem.homepage = "http://github.com/kristianmandrup/timespan"
   gem.license = "MIT"
-  gem.summary = %Q{Use TimeSpans in ruby}
-  gem.description = %Q{Easy to calculate time distance in different units}
+  gem.summary = %Q{Use timespans in ruby}
+  gem.description = %Q{Makes it easy to calculate time distance in different units}
   gem.email = "kmandrup@gmail.com"
   gem.authors = ["Kristian Mandrup"]
   # dependencies defined in Gemfile

data/VERSION

@@ -1 +1 @@
-0.1.4
+0.2.0

data/config/locales/timespan/da.yml

@@ -0,0 +1,5 @@
+da:
+  timespan:
+    from: fra
+    to: til
+    lasting: der varer ialt

data/lib/timespan.rb

@@ -1,217 +1,211 @@
 require 'duration'
+require 'chronic'
+require 'chronic_duration'
 require 'spanner'
 
-class TimeSpan
-	class ParseError < StandardError; end
+require 'timespan/units'
+require 'timespan/compare'
+require 'timespan/printer'
+require 'timespan/span'
 
-	attr_reader :start_time, :end_time, :seconds
+if defined?(Rails) && Rails::VERSION::STRING.to >= '3.1'
+	require 'duration/rails/engine' 
+end
+
+class Timespan
+	include Span
+	include Printer
+	include Compare
+	include Units
+
+	class TimeParseError < StandardError; end	
+
+	attr_reader :start_time, :end_time
 
 	alias_method :start_date, :start_time
 	alias_method :end_date, 	:end_time
 
+	START_KEYS 			= [:start, :from]
+	END_KEYS 				= [:to, :end]
+	DURATION_KEYS 	= [:duration, :lasting]
+
+	ALL_KEYS = START_KEYS + END_KEYS + DURATION_KEYS
+
 	def initialize options = {}
 		@is_new = true
 
-		set_with_options options		
+		case options
+		when Numeric, Duration, String
+			options = {:duration => options}
+		end
+		
+		configure options		
 		
 		@is_new = false
 	end
 
-	def start_time= start_time
-		@start_time = start_time
-		refresh!
+	def start_time= time
+		@start_time = convert_to_time time		
+		unless is_new?
+			refresh!
+			add_dirty :start
+			calculate!
+		end
 	end
 	alias_method :start_date=, :start_time=
-
-	def end_time= start_time
-		@start_time = start_time
-		refresh!
+	
+	def from time
+		self.start_time =	time
+		self
+	end
+
+	def end_time= time
+		@end_time = convert_to_time time
+		unless is_new?
+			add_dirty :end
+			refresh!
+			calculate!
+		end
 	end
 	alias_method :end_date=, :end_time=
 
-	def seconds= seconds 
-		@seconds = seconds
-		refresh!	
+	def until time
+		self.end_time =	time
+		self
 	end
 
-	def duration
-		@duration ||= Duration.new(seconds)
-	end
-
-	def duration= duration
-		@duration = case duration
-		when Duration
-			duration
-		when Integer, Hash
-			Duration.new duration
+	def convert_to_time time
+		case time
 		when String
-			begin				
-				Duration.new Spanner.parse(duration.gsub /and/, '')
-			rescue Exception => e
-				raise ParseError, "Internal error: Spanner couldn't parse String '#{duration}'"
-			end
+			Chronic.parse(time)
+		when Date, DateTime
+			time.to_time
+		when Time
+			time
 		else
-			raise ArgumentError, "the duration option must be set to any of: #{valid_duration_types}"
-		end		 
-		refresh! unless is_new?
-	end
-		
-	def to_s
-		if duration
-			"TimeSpan: from #{start_time} lasting #{duration} = #{seconds} secs" if start_time
-			"TimeSpan: from #{end_time} to #{duration} before = #{seconds} secs" if end_time
-			return
+			raise ArgumentError, "A valid time must be either a String, Date, Time or DateTime, was: #{time.inspect}"
 		end
+	end
 
-		if start_time && end_time
-			"TimeSpan: #{start_time} to #{end_time} = #{seconds} secs"			
-			return
-		end
+	protected
 
-		if seconds
-			"TimeSpan: #{seconds} seconds"
-		end
+	def first_from keys, options = {}
+		keys.select {|key| options[key] }.first
 	end
 
-	include Comparable
-
-  def <=> time
-  	raise ArgumentError, "Not a valid argument for timespan comparison, was #{time}" unless valid_compare?(time)
-  	case time
-  	when TimeSpan
-  		millis <=> time.seconds
-  	when Time  		
-    	millis <=> time.to_i
-    when Date, DateTime
-    	time.to_time.to_i
-    when Integer
-    	millis <=> time
-    end
-  end
-
-	alias_method :to_secs, 		:seconds
-	alias_method :to_seconds, :seconds
-
-	def to_milliseconds
-		@to_seconds ||= (seconds * 1000.0).round
-	end
-	alias_method :to_mils, 	 			:to_milliseconds
-	alias_method :millis, 	 			:to_mils
-	alias_method :milliseconds, 	:to_mils
-
-	def to_minutes
-		@to_minutes ||= (to_seconds / 60.0).round
-	end
-	alias_method :to_m, 		:to_minutes
-	alias_method :to_mins, 	:to_minutes
-	alias_method :minutes, 	:to_minutes
-
-	def to_hours
-		@to_hours ||= (to_minutes / 60.0).round
-	end
-	alias_method :to_h, 	:to_hours
-	alias_method :hrs, 		:to_hours
-	alias_method :hours, 	:to_hours
-
-	def to_days
-		@to_days ||= (to_hours / 24.0).round
-	end	
-	alias_method :to_d, :to_days
-	alias_method :days, :to_days
-
-	def to_weeks
-		@to_weeks ||= (to_days / 7.0).round
-	end	
-	alias_method :to_w, 	:to_weeks
-	alias_method :weeks, 	:to_days
-
-	def to_months
-		@to_months ||= (to_days / 30.0).round
-	end	
-	alias_method :to_mon, :to_months
-	alias_method :months, :to_months
-
-	def to_years
-		@to_years ||= (to_days.to_f / 365.25).round
-	end	
-	alias_method :to_y, 	:to_years
-	alias_method :years, 	:to_years
-
-	def to_decades
-		@to_decades ||= (to_years / 10.0).round
-	end	
-	alias_method :decades, 	:to_decades
-
-	def to_centuries
-		@to_centuries ||= (to_decades / 10.0).round
-	end	
-	alias_method :centuries, 	:to_centuries
-
-	def units
-		%w{seconds minutes hours days weeks months years}
-	end
+	def configure options = {}		
+		from 	= options[first_from START_KEYS, options]
+		to 		= options[first_from END_KEYS, options]
+		dur 	= options[first_from DURATION_KEYS, options]
 
-	protected
+		self.duration 		= dur if dur
+		self.start_time 	= from if from
+		self.end_time 		= to if to
 
-	def set_with_options options = {}		
-		case options
-		when Hash
-			duration 		= options[:duration]
-			@start_time = options[:from] || options[:start]
-			@end_time 	= options[:to] || options[:end]
-		when Integer, String
-			duration   = options
-		else
-			raise ArgumentError, "Timespan must take Hash or Integer, was: #{options}"
-		end
+		default_from_now! unless start_time || end_time
 
-		set_seconds options
+		calculate_miss!
+	rescue Exception => e
+		calculate_miss!
+		validate!
 	end		
 
-	def set_seconds options = nil
-		set_seconds_opts(options)
+	def default_from_now!
+		self.start_time = Time.now
+	end
 
-		unless @duration
-			if @end_time && @start_time
-				@seconds 	||= (@end_time - @start_time).to_i
-			end
-		else
-			@seconds 	||= @duration.total
-		end
+	def validate!	
+		raise ArgumentError, "#{valid_requirement}, was: #{current_config}" unless valid?
 	end
 
-	def set_seconds_opts options = {}
-		case options
-		when Integer
-			@seconds = options
-		when Hash
-			@seconds = options[:seconds] if options[:seconds]
-			self.duration = options[:duration] if options[:duration]
-		end
+	def valid_requirement
+		"Timespan must take a :start and :end time or any of :start and :end time and a :duration"
+	end
+
+	def current_config
+		"end time: #{end_time}, start time: #{start_time}, duration: #{duration}"
+	end
+
+	def valid?
+		(end_time && start_time) || (end_time || start_time && duration)
 	end
 
 	def is_new?
 		@is_new
 	end
 
-	# reset all stored instance vars for units
-	def refresh!
-		units.each do |unit| 
-			var_name = :"@#{unit}"
-			instance_variable_set var_name, nil
-		end
-		set_seconds
+	def dirty
+		@dirty ||= []
+	end
+
+	def add_dirty type
+		reset_dirty if dirty.size > 2
+		dirty << type
+	end
+
+	def reset_dirty
+		@dirty = []
+	end
+
+	def dirty? type
+		dirty.include? type
+	end
+
+	def calculate!
+		set_duration unless dirty? :duration
+		set_start_time unless dirty? :start
+		set_end_time unless dirty? :end		
+	end
+
+	def calculate_miss!
+		set_end_time_miss
+		set_start_time_miss	
+		set_duration_miss
+		set_end_time_miss	
+		set_start_time_miss
+	end
+
+	def set_end_time_miss		
+		set_end_time if missing_end_time?
+	end
+
+	def set_end_time
+		self.end_time = start_time - duration.total
+	end
+
+	def set_start_time_miss
+		 set_start_time if missing_start_time?
+	end
+
+	def set_start_time
+		self.start_time = end_time - duration.total
+	end
+
+	def set_duration_miss
+		set_duration if missing_duration?
+	end
+
+	def set_duration
+		self.duration = end_time - start_time
 	end
 
-	def valid_duration_types
-		[Duration, String, Integer, Hash]
+	def missing_end_time?
+		start_time && duration && !end_time
 	end
 
-	def valid_compare? time
-		valid_compare_types.any? {|type| time.kind_of? type }
+	def missing_start_time?
+		end_time && duration && !start_time
 	end
 
-	def valid_compare_types
-		[TimeSpan, Time, Date, DateTime, Integer]
+	def missing_duration?
+		start_time && end_time && !duration
+	end
+
+	# reset all stored instance vars for units
+	def refresh!
+		units.each do |unit| 
+			var_name = :"@#{unit}"
+			instance_variable_set var_name, nil
+		end
 	end
 end