time_of_day 0.1.1

data/.document

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

data/.gitignore

@@ -0,0 +1,23 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+pkg/*
+*.gem
+.bundle
+Gemfile.lock
+
+## PROJECT::SPECIFIC
+.rvmrc

data/Gemfile

@@ -0,0 +1,4 @@
+source :gemcutter
+
+# Specify your gem's dependencies in time_of_day.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Lailson Bandeira
+
+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.rdoc

@@ -0,0 +1,117 @@
+= time_of_day
+
+Have you already worked with a database Time column and an Active Record model together?
+If you had, you know: it sucks. Well, not anymore.
+
+== Setup
+
+In the +Gemfile+ add:
+  
+  gem 'time_of_day', :git => 'git://github.com/lailsonbm/time_of_day'
+
+Run +bundler+:
+
+  bundle install
+
+Just that.
+
+== The problem
+
+Sometimes we need to work with time-only objects.
+Suppose, for example, you're working on a train table web application and want to register
+trips between stations. Every day, the train departures on a defined time and, some minutes
+later, it arrives at the next station.
+
+So lets dive into Rails and do it. You'll end up with a migration and a model like this:
+  
+  # Migration
+  class CreateTrips < ActiveRecord::Migration
+    def self.up
+      create_table :trips do |t|
+        t.string :train, :leaving_from, :arriving_at
+        t.time :departure, :arrival
+      end
+    end
+
+    def self.down
+      drop_table :trips
+    end
+  end
+  
+  # Dumb AR model
+  class Trip < ActiveRecord::Base
+  end
+
+Cool. Just after a <code>rake db:migrate</code>, we can create trips and tell if the train will be
+on any of them at a given time:
+
+  trip = Trip.new
+  trip.departure = '10:00'
+  trip.arrival = '10:10'
+  
+  # Will the train be on this trip at 10:05?
+  time = Time.parse('10:05')
+  (trip.departure..trip.arrival).cover?(time) # OR
+  (trip.departure <= time && trip.arrival >= time) # if you are old fashioned =P
+  
+You might be surprised to know: this code does not work. At least not as we expected: both 
+statements return false. The problem is caused by the way Active Record handles time-only attributes.
+SQL has the +time+ data type, that represents just a time of day, but Ruby doesn't 
+have such thing. So, Active Record represent time attributes using the +Time+ class on
+the canonical (and arbitrary) date <code>2000-01-01</code>. This is okay when you are comparing only attributes
+since their date will be equal and just the time will be compared. However, when you compare an
+attribute with another time instance, you start to need silly workarounds. In this case, the code does not work
+because <code>Time#parse</code> yields the current date (e.g. <code>2010-06-25 10:05</code>) and of course it is not between 
+<code>2000-01-01 10:00</code> and <code>2000-01-01 10:10</code>. To accomplish what you were trying to do, you have two alternatives:
+
+  # Always use the date 01/01/2000 for any time you want to compare (notice the Z for UTC time zone)
+  time = Time.parse('2000-01-01 10:05Z')
+  (trip.departure..trip.arrival).cover?(time) # => true
+  
+  # OR compare always considering the seconds since midnight
+  seconds = time.seconds_since_midnight
+  (trip.departure.seconds_since_midnight <= seconds && trip.arrival.seconds_since_midnight >= seconds) # => true
+
+Sorry, but both options suck.
+
+== How time_of_day handles the problem
+
+There are many ways to fix this issue. Subclassing +Time+ would be certainly the purest OO
+solution, but I found that monkey patching it is much more practical. So, it's what +time_of_day+
+does. It adds some methods to +Time+ for representing times of day, instead of time with dates.
+  
+  # Suppose today is June 25, 2010
+  time1 = Time.parse('10:00') # => 2010-06-25 10:00:00
+  time2 = Time.parse('2010-06-01 10:00') # => 2010-06-01 10:00:00
+  time1 == time2 # => false
+  
+  # Ignoring the dates
+  time1.time_of_day!
+  time2.time_of_day! 
+  time1 == time2 # => true
+  
+So, now you can ignore the date information and compare just time. The most exciting thing, 
+though, is that Active Record time attributes are now always mapped to times of day:
+
+  trip = Trip.new
+  trip.departure = '10:00'
+  trip.arrival = '10:10'
+  
+  trip.departure.time_of_day? # => true
+  trip.arrival.time_of_day? # => true
+  
+At this time, the code works effortlessly:
+
+  time = Time.parse('10:05').time_of_day!
+  (trip.departure..trip.arrival).cover?(time) # => true
+  (trip.departure <= time && trip.arrival >= time) # => true
+  
+And you go home earlier.
+
+== Compatibility
+ 
+Tested with Rails 3.0.0 on Ruby 1.9.2-p0 and Ruby 1.8.7.
+
+== Copyright
+
+Copyright (c) 2010 Lailson Bandeira (http://lailsonbandeira.com). See LICENSE for details.

data/Rakefile

@@ -0,0 +1,12 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake'
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test

data/lib/time_of_day.rb

@@ -0,0 +1,5 @@
+require 'time_of_day/ext/time'
+require 'time_of_day/ext/active_record'
+
+module TimeOfDay
+end

data/lib/time_of_day/ext/active_record.rb

@@ -0,0 +1,16 @@
+require 'active_support/core_ext/module/aliasing'
+require 'active_record/connection_adapters/abstract/schema_definitions'
+
+module ActiveRecord
+  module ConnectionAdapters
+    class Column
+      class << self
+        def string_to_dummy_time_with_time_of_day(string)
+          t = string_to_dummy_time_without_time_of_day(string)
+          t.respond_to?(:time_of_day) ? t.time_of_day : t
+        end
+        alias_method_chain :string_to_dummy_time, :time_of_day
+      end
+    end
+  end
+end

data/lib/time_of_day/ext/time.rb

@@ -0,0 +1,49 @@
+require 'active_support/core_ext/module/aliasing'
+require 'active_support/core_ext/time/conversions'
+
+class Time
+  DATE_FORMATS[:time_utc] = '%H:%M:%S'
+  
+  def time_of_day?
+    @time_of_day ||= false
+  end
+  
+  def time_of_day
+    self.dup.time_of_day!
+  end
+  
+  def time_of_day!
+    @time_of_day = true
+    self
+  end
+  
+  def not_time_of_day
+    self.dup.not_time_of_day!
+  end
+  
+  def not_time_of_day!
+    @time_of_day = false
+    self
+  end
+  
+  def compare_with_time_of_day(time)
+    if self.time_of_day? && time.time_of_day?
+      self.seconds_since_midnight <=> time.seconds_since_midnight
+    else
+      self.compare_without_time_of_day(time)
+    end
+  rescue
+    self.compare_without_time_of_day(time)
+  end
+  alias_method :compare_without_time_of_day, :<=>
+  alias_method :<=>, :compare_with_time_of_day
+  
+  def to_s_with_time_of_day(format=nil)
+    unless format
+      to_s_without_time_of_day(:time_utc)
+    else
+      to_s_without_time_of_day(format)
+    end
+  end
+  alias_method_chain :to_s, :time_of_day
+end

data/lib/time_of_day/version.rb

@@ -0,0 +1,3 @@
+module TimeOfDay
+  VERSION = '0.1.1'
+end

data/test/helper.rb

@@ -0,0 +1,35 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'time_of_day'
+
+require 'active_support/all'
+
+class Test::Unit::TestCase
+end
+
+# ACTIVE RECORD STUFF
+require 'active_record'
+class User < ActiveRecord::Base; end
+def load_schema
+  ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => ":memory:")
+  
+  # Avoids printing create table statements
+  silence_stream(STDOUT) do |variable|
+    ActiveRecord::Schema.define(:version => 1) do
+      create_table :users do |t|
+        t.string :name
+        t.date :birth_date
+        t.time :arrival_time
+        t.datetime :join_datetime
+        t.timestamp :last_operation_timestamp
+      end
+    end
+  end
+end
+
+
+

data/test/test_active_record_extensions.rb

@@ -0,0 +1,32 @@
+require 'helper'
+
+class TestActiveRecordExtensions < Test::Unit::TestCase
+  context "An attribute of type time from an active record model" do
+    load_schema
+    
+    setup do
+      @user = User.new
+    end
+
+    should "be parsed as a time of day object" do
+      @user.arrival_time = '10:00'
+      assert_kind_of Time, @user.arrival_time
+    end
+    
+    should "be converted to time of day object" do
+      time = Time.parse('10:00')
+      @user.arrival_time = time
+      assert !time.time_of_day?
+      assert @user.arrival_time.time_of_day?
+    end
+    
+    should "be loaded from database as time of day" do
+      User.destroy_all
+      @user.arrival_time = '10:00'
+      @user.save!
+      
+      assert User.first.arrival_time.time_of_day?
+    end
+  end
+  
+end

data/test/test_time_extensions.rb

@@ -0,0 +1,78 @@
+require 'helper'
+
+class TestTimeExtensions < Test::Unit::TestCase
+  context "A Time object" do
+    setup do
+      @time = Time.parse('08:00')
+    end
+    
+    should "have time of day methods" do
+      assert_respond_to @time, :time_of_day?
+      assert_respond_to @time, :time_of_day
+      assert_respond_to @time, :time_of_day!
+      assert_respond_to @time, :not_time_of_day
+      assert_respond_to @time, :not_time_of_day!
+    end
+    
+    should "be not a time of day by default" do
+      assert !@time.time_of_day?
+    end
+    
+    should "be convertible to time of day" do
+      @time.time_of_day!
+      assert @time.time_of_day?
+    end
+    
+    should "be capable of generate a time of day version of itself" do
+      time_of_day = @time.time_of_day
+      
+      assert !@time.time_of_day?
+      assert time_of_day.time_of_day?
+    end
+    
+    context "that represents a time of day" do
+      setup do
+        @time.time_of_day!
+      end
+
+      should "be convertible to an ordinary time object" do
+        @time.not_time_of_day!
+        assert !@time.time_of_day?
+      end
+      
+      should "be capable of generate an ordinary time version of itself" do
+        ordinary_time = @time.not_time_of_day
+        assert @time.time_of_day?
+        assert !ordinary_time.time_of_day?
+      end
+      
+      should "compare to other time of day objects using only time information" do
+        time1 = Time.parse('2000-01-01 08:00').time_of_day!
+        time2 = Time.parse('2000-01-10 08:00').time_of_day!
+        time3 = Time.parse('2010-06-15 10:00').time_of_day!
+        assert_equal 0, (time1 <=> time2)
+        assert_equal 1, (time3 <=> time1)
+        assert_equal -1, (time1 <=> time3)
+      end
+      
+      should "compare to any other time object using Time's comparison" do
+        time1 = Time.parse('2005-01-01 08:00').time_of_day!
+        time2 = Time.parse('2000-01-10 10:00')
+        time3 = Time.parse('2010-06-15 06:00')
+        assert_equal 1, (time1 <=> time2)
+        assert_equal -1, (time1 <=> time3)
+      end
+      
+      should "compare to any other object using Time's comparision" do
+        assert_nothing_raised do
+          assert_nil (@time <=> 'string')
+          assert_nil (@time <=> :symbol)
+        end
+      end
+      
+      should "convert to string using UTC time notation when to_s is called without arguments" do
+        assert_equal '08:00:00', @time.to_s
+      end
+    end
+  end
+end

data/time_of_day.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/time_of_day/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = 'time_of_day'
+  s.version     = TimeOfDay::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = %q{Lailson Bandeira}
+  s.email       = %q{lailson@guava.com.br}
+  s.homepage    = 'http://rubygems.org/gems/time_of_day'
+  s.summary     = 'Handle correctly times without dates in Rails 3.'
+  s.description = 'Adds time-only capabilities to the Time class and maps the Rails time type correctly to a time without date.'
+
+  s.required_rubygems_version = '>= 1.3.6'
+  s.rubyforge_project         = 'time_of_day'
+
+  s.add_development_dependency 'bundler', '>= 1.0.0'
+  s.add_development_dependency 'shoulda', '>= 2.11.3'
+  s.add_runtime_dependency('activesupport', '>= 3.0.0')
+  s.add_runtime_dependency('activerecord', '>= 3.0.0')
+
+  s.files        = `git ls-files`.split("\n")
+  s.executables  = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact
+  s.require_path = 'lib'
+end

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification 
+name: time_of_day
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
+platform: ruby
+authors: 
+- Lailson Bandeira
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-26 00:00:00 -03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 11
+        - 3
+        version: 2.11.3
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id004
+description: Adds time-only capabilities to the Time class and maps the Rails time type correctly to a time without date.
+email: lailson@guava.com.br
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .document
+- .gitignore
+- Gemfile
+- LICENSE
+- README.rdoc
+- Rakefile
+- lib/time_of_day.rb
+- lib/time_of_day/ext/active_record.rb
+- lib/time_of_day/ext/time.rb
+- lib/time_of_day/version.rb
+- test/helper.rb
+- test/test_active_record_extensions.rb
+- test/test_time_extensions.rb
+- time_of_day.gemspec
+has_rdoc: true
+homepage: http://rubygems.org/gems/time_of_day
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: time_of_day
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Handle correctly times without dates in Rails 3.
+test_files: []
+