timecop 0.2.1 → 0.3.0

data/History.txt

@@ -1,9 +1,29 @@
+=== 0.3.0 / 2009-09-20
+
+* API
+  * Completely remove Timecop#unset_all (deprecated by Timecop#return in 0.2.0)
+  * Return Time.now from #freeze, #travel and #return  -- code contributed by Keith Bennett (keithrbennett)
+
+* Maintenance
+  * Fix bug that left Time#mock_time set in some instances
+  * Upped build dependency to jeweler ~> 1.0.2
+
+* Documentation
+  * Clearer examples in the README, better description in the gemspec
+  * Improve RDoc
+
 === 0.2.1 / 2009-03-06
 * API Changes
   
   * Introduced a 5th style of arguments to be passed into #travel and #freeze.  Now, if you pass in a single integer value,
     it will be interpreted as a relative offset in seconds from the current Time.now.  Previously this was interpreted as
     only the year, similar to calling Time.local(2008) --> Jan. 1, 2008.  This is no longer the case.
+    
+* Documentation
+
+  * Moved to Textile for the README.
+  
+  * Added documentation for the new feature, and fixed a few typos.
 
 === 0.2.0 / 2008-12-23
 

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2008
+
+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,69 @@
+= timecop
+
+* http://github.com/jtrupiano/timecop
+
+== DESCRIPTION
+
+A gem providing "time travel" and "time freezing" capabilities, making it dead simple to test time-dependent code.  It provides a unified method to mock Time.now, Date.today, and DateTime.now in a single call.
+
+== FEATURES
+
+* Freeze time to a specific point.
+* Travel back to a specific point in time, but allow time to continue moving forward from there.
+* Timecop api allows arguments to be passed into #freeze and #travel as one of the following:
+  * Time instance
+  * DateTime instance
+  * Date instance
+  * individual arguments (year, month, day, hour, minute, second)
+  * a single integer argument that is interpreted as an offset in seconds from Time.now
+* Nested calls to Timecop#travel and Timecop#freeze are supported -- each block will maintain its interpretation of now.
+
+== USAGE
+
+Run a time-sensitive test
+
+  joe = User.find(1)
+  joe.purchase_home()
+  assert !joe.mortgage_due?
+  # move ahead a month and assert that the mortgage is due
+  Timecop.freeze(Date.today + 30) do
+    assert joe.mortgage_due?
+  end
+
+Set the time for the test environment of a rails app -- this is particularly helpful if your whole application is time-sensitive.  It allows you to build your test data at a single point in time, and to move in/out of that time as appropriate (within your tests)
+  
+in config/environments/test.rb
+
+  config.after_initialize do
+    # Set Time.now to September 1, 2008 10:05:00 AM (at this instant), but allow it to move forward
+    t = Time.local(2008, 9, 1, 10, 5, 0)
+    Timecop.travel(t)
+  end
+
+=== The difference between Timecop.freeze and Timecop.travel
+
+#freeze is used to statically mock the concept of now.  As your program executes, Time.now will not change unless you make subsequent calls into the Timecop API.  #travel, on the other hand, computes an offset between what we currently think Time.now is (recall that we support nested traveling) and the time passed in.  It uses this offset to simulate the passage of time.  To demonstrate, consider the following code snippets:
+
+  new_time = Time.local(2008, 9, 1, 12, 0, 0)
+  Timecop.freeze(new_time)
+  sleep(10)
+  new_time == Time.now # ==> true
+  
+  Timecop.return # "turn off" Timecop
+  Timecop.travel(new_time)
+  sleep(10)
+  new_time == Time.now # ==> false
+
+== DEPENDENCIES
+
+* None
+
+== INSTALL
+
+* sudo gem install timecop (latest stable version from rubyforge)
+* sudo gem install jtrupiano-timecop (HEAD of the repo from github)
+
+== REFERENCES
+
+* "0.2.0 release":http://blog.smartlogicsolutions.com/2008/12/24/timecop-2-released-freeze-and-rebase-time-ruby/
+* "0.1.0 release":http://blog.smartlogicsolutions.com/2008/11/19/timecop-freeze-time-in-ruby-for-better-testing/

data/Rakefile

@@ -2,18 +2,23 @@ require 'rake'
 require 'rake/testtask'
 require 'rake/rdoctask'
 
+gem 'jeweler', '~> 1.2.1'
+
 begin
   require 'jeweler'
   Jeweler::Tasks.new do |s|
     s.name = "timecop"
     s.rubyforge_project = 'johntrupiano' # if different than lowercase project name
-    s.description = %q(A gem providing simple ways to temporarily override Time.now, Date.today, and DateTime.now.  It provides "time travel" capabilities, making it dead simple to test time-dependent code.)
+    s.description = %q(A gem providing "time travel" and "time freezing" capabilities, making it dead simple to test time-dependent code.  It provides a unified method to mock Time.now, Date.today, and DateTime.now in a single call.)
     s.summary = s.description # More details later??
     s.email = "jtrupiano@gmail.com"
     s.homepage = "http://github.com/jtrupiano/timecop"
     s.authors = ["John Trupiano"]
     s.files =  FileList["[A-Z]*", "{bin,lib,test}/**/*"]
-    #s.add_dependency 'schacon-git'
+  end
+  Jeweler::RubyforgeTasks.new do |rubyforge|
+    rubyforge.doc_task = "rdoc"
+    rubyforge.remote_doc_path = "timecop"
   end
 rescue LoadError
   puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
@@ -29,3 +34,21 @@ task :test do
     to automate them.
   MSG
 end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.title = "timecop #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('History.txt')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :default => :test

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
+:minor: 3
+:patch: 0
 :major: 0
-:minor: 2
-:patch: 1

data/lib/timecop.rb

@@ -1,3 +1,2 @@
-# place gem dependencies here...
-#require 'timecop/timecop'
+# Require Timecop 
 require File.join(File.dirname(__FILE__), 'timecop', 'timecop')

data/lib/timecop/stack_item.rb

@@ -1,11 +1,12 @@
 
-# Simply a data class for carrying around "time movement" objects.  Makes it easy to keep track of the time
-# movements on a simple stack.
-class StackItem
+class Timecop
+  # Simply a data class for carrying around "time movement" objects.  Makes it easy to keep track of the time
+  # movements on a simple stack.
+  class StackItem #:nodoc:
   
-  attr_reader :mock_type, :year, :month, :day, :hour, :minute, :second
-  def initialize(mock_type, year, month, day, hour, minute, second)
-    @mock_type, @year, @month, @day, @hour, @minute, @second = mock_type, year, month, day, hour, minute, second
+    attr_reader :mock_type, :year, :month, :day, :hour, :minute, :second
+    def initialize(mock_type, year, month, day, hour, minute, second)
+      @mock_type, @year, @month, @day, @hour, @minute, @second = mock_type, year, month, day, hour, minute, second
+    end
   end
-end
-
+end

data/lib/timecop/time_extensions.rb

@@ -1,10 +1,11 @@
+#--
 # 1. Extensions to the Time, Date, and DateTime objects
 # 2. Allows us to "freeze" time in our Ruby applications.
 # 3. This is very useful when your app's functionality is dependent on time (e.g. 
 # anything that might expire).  This will allow us to alter the return value of
 # Date.today, Time.now, and DateTime.now, such that our application code _never_ has to change.
 
-class Time
+class Time #:nodoc:
   class << self
     # Time we might be behaving as
     #attr_reader :mock_time
@@ -50,7 +51,7 @@ class Time
 end 
 
 if Object.const_defined?(:Date)
-  class Date
+  class Date #:nodoc:
     class << self
       def mock_date
         now = Time.mock_time
@@ -73,7 +74,7 @@ if Object.const_defined?(:Date)
 end
 
 if Object.const_defined?(:DateTime)
-  class DateTime
+  class DateTime #:nodoc:
     class << self
       def mock_time
         t_now = Time.mock_time

data/lib/timecop/timecop.rb

@@ -17,24 +17,23 @@ class Timecop
   # This is particularly useful for writing test methods where the passage of time is critical to the business
   # logic being tested.  For example:
   #
-  # <code>
   #   joe = User.find(1)
   #   joe.purchase_home()
   #   assert !joe.mortgage_due?
   #   Timecop.freeze(2008, 10, 5) do
   #     assert joe.mortgage_due?
   #   end
-  # </code>
   #
   # freeze and travel will respond to several different arguments:
   # 1. Timecop.freeze(time_inst)
   # 2. Timecop.freeze(datetime_inst)
   # 3. Timecop.freeze(date_inst)
-  # 4. Timecop.freeze(year, month, day, hour=0, minute=0, second=0)
+  # 4. Timecop.freeze(offset_in_seconds)
+  # 5. Timecop.freeze(year, month, day, hour=0, minute=0, second=0)
   #
   # When a block is also passed, Time.now, DateTime.now and Date.today are all reset to their
-  # previous values.  This allows us to nest multiple calls to Timecop.travel and have each block
-  # maintain it's concept of "now."
+  # previous values after the block has finished executing.  This allows us to nest multiple 
+  # calls to Timecop.travel and have each block maintain it's concept of "now."
   #
   # * Note: Timecop.freeze will actually freeze time.  This can cause unanticipated problems if
   #   benchmark or other timing calls are executed, which implicitly expect Time to actually move
@@ -44,39 +43,41 @@ class Timecop
   #   rails project.  Generators will load your environment, including the migration generator, 
   #   which will lead to files being generated with the timestamp set by the Timecop.freeze call 
   #   in your dev environment
+  #
+  # Returns the frozen time.
   def self.freeze(*args, &block)
     instance().send(:travel, :freeze, *args, &block)
+    Time.now
   end
   
   # Allows you to run a block of code and "fake" a time throughout the execution of that block.
   # See Timecop#freeze for a sample of how to use (same exact usage syntax)
   #
   # * Note: Timecop.travel will not freeze time (as opposed to Timecop.freeze).  This is a particularly
-  #   good candidate for use in environment files in rails projects.  
+  #   good candidate for use in environment files in rails projects.
+  #
+  # Returns the 'new' current Time.
   def self.travel(*args, &block)
     instance().send(:travel, :move, *args, &block)
+    Time.now
   end
   
   # Reverts back to system's Time.now, Date.today and DateTime.now (if it exists). If freeze_all or rebase_all
   # was never called in the first place, this method will have no effect.
+  #
+  # Returns Time.now, which is now the real current time.
   def self.return
     instance().send(:unmock!)
+    Time.now
   end
 
-  # [Deprecated]: See Timecop#return instead.
-  def self.unset_all
-    $stderr.puts "Timecop#unset_all is deprecated.  Please use Timecop#return instead."
-    $stderr.flush
-    self.return
-  end
-  
   protected
   
-    def initialize
+    def initialize #:nodoc:
       @_stack = []
     end
     
-    def travel(mock_type, *args, &block)
+    def travel(mock_type, *args, &block) #:nodoc:
       # parse the arguments, build our base time units
       year, month, day, hour, minute, second = parse_travel_args(*args)
 
@@ -111,7 +112,8 @@ class Timecop
       end
     end
   
-    def unmock!
+    def unmock! #:nodoc:
+      @_stack = []
       Time.unmock!
     end
   
@@ -174,25 +176,3 @@ class Timecop
       return year, month, day, hour, minute, second
     end
 end
-
-#def with_dates(*dates, &block)
-#  dates.flatten.each do |date|
-#    begin
-#      DateTime.forced_now = case date
-#        when String: DateTime.parse(date)
-#        when Time: DateTime.parse(date.to_s)
-#        else
-#          date
-#      end
-#      Date.forced_today = Date.new(DateTime.forced_now.year,
-#DateTime.forced_now.month, DateTime.forced_now.day)
-#      yield
-#    rescue Exception => e
-#      raise e
-#    ensure
-#      DateTime.forced_now = nil
-#      Date.forced_today = nil
-#    end
-#  end
-#end 
-

data/test/test_timecop.rb

@@ -26,6 +26,30 @@ class TestTimecop < Test::Unit::TestCase
     assert_not_equal t, Time.now
   end
   
+  def test_freeze_then_return_unsets_mock_time
+    Timecop.freeze(1)
+    Timecop.return
+    assert_nil Time.send(:mock_time)
+  end
+
+  def test_travel_then_return_unsets_mock_time
+    Timecop.travel(1)
+    Timecop.return
+    assert_nil Time.send(:mock_time)
+  end
+  
+  def test_freeze_with_block_unsets_mock_time
+    assert_nil Time.send(:mock_time), "test is invalid"
+    Timecop.freeze(1) do; end
+    assert_nil Time.send(:mock_time)
+  end
+  
+  def test_travel_with_block_unsets_mock_time
+    assert_nil Time.send(:mock_time), "test is invalid"
+    Timecop.travel(1) do; end
+    assert_nil Time.send(:mock_time)
+  end
+  
   def test_recursive_freeze
     t = Time.local(2008, 10, 10, 10, 10, 10)
     Timecop.freeze(2008, 10, 10, 10, 10, 10) do 
@@ -142,7 +166,6 @@ class TestTimecop < Test::Unit::TestCase
       end
       assert((t - Time.now).abs < 2000, "Failed to restore previously-traveled time.")
     end
-    assert_nil Time.send(:mock_time)
   end
   
   def test_recursive_travel_then_freeze
@@ -155,7 +178,6 @@ class TestTimecop < Test::Unit::TestCase
       end
       assert((t - Time.now).abs < 2000, "Failed to restore previously-traveled time.")
     end
-    assert_nil Time.send(:mock_time)
   end
   
   def test_recursive_freeze_then_travel
@@ -169,7 +191,40 @@ class TestTimecop < Test::Unit::TestCase
       end
       assert_equal t, Time.now
     end
-    assert_nil Time.send(:mock_time)    
   end
   
+  def test_return_values_are_Time_instances
+    assert Timecop.freeze.is_a?(Time)
+    assert Timecop.travel.is_a?(Time)
+    assert Timecop.return.is_a?(Time)
+  end
+  
+  def test_travel_time_returns_passed_value
+    t_future = Time.local(2030, 10, 10, 10, 10, 10)
+    t_travel = Timecop.travel t_future
+    assert times_effectively_equal(t_future, t_travel)
+  end
+  
+  def test_freeze_time_returns_passed_value
+    t_future = Time.local(2030, 10, 10, 10, 10, 10)
+    t_frozen = Timecop.freeze t_future
+    assert times_effectively_equal(t_future, t_frozen)
+  end
+  
+  def test_return_time_returns_actual_time
+    t_real = Time.now
+    Timecop.freeze Time.local(2030, 10, 10, 10, 10, 10)
+    t_return = Timecop.return
+    assert times_effectively_equal(t_real, t_return)
+  end
+
+
+private
+
+  # Tests to see that two times are within the given distance,
+  # in seconds, from each other.
+  def times_effectively_equal(time1, time2, seconds_interval = 1)
+    (time1.to_i - time2.to_i).abs <= seconds_interval
+  end
+    
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: timecop
 version: !ruby/object:Gem::Version 
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors: 
 - John Trupiano
@@ -9,39 +9,39 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-06 00:00:00 -05:00
+date: 2009-09-20 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
-description: A gem providing simple ways to temporarily override Time.now, Date.today, and DateTime.now.  It provides "time travel" capabilities, making it dead simple to test time-dependent code.
+description: A gem providing "time travel" and "time freezing" capabilities, making it dead simple to test time-dependent code.  It provides a unified method to mock Time.now, Date.today, and DateTime.now in a single call.
 email: jtrupiano@gmail.com
 executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
 files: 
 - History.txt
-- Manifest.txt
+- LICENSE
+- README.rdoc
 - Rakefile
-- README.textile
 - VERSION.yml
-- lib/timecop
+- lib/timecop.rb
 - lib/timecop/stack_item.rb
 - lib/timecop/time_extensions.rb
 - lib/timecop/timecop.rb
-- lib/timecop/version.rb
-- lib/timecop.rb
 - test/run_tests.sh
 - test/test_timecop.rb
 - test/test_timecop_internals.rb
 - test/test_timecop_without_date.rb
 has_rdoc: true
 homepage: http://github.com/jtrupiano/timecop
+licenses: []
+
 post_install_message: 
 rdoc_options: 
-- --inline-source
 - --charset=UTF-8
 require_paths: 
 - lib
@@ -60,9 +60,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: johntrupiano
-rubygems_version: 1.3.1
+rubygems_version: 1.3.5
 signing_key: 
-specification_version: 2
-summary: A gem providing simple ways to temporarily override Time.now, Date.today, and DateTime.now.  It provides "time travel" capabilities, making it dead simple to test time-dependent code.
-test_files: []
-
+specification_version: 3
+summary: A gem providing "time travel" and "time freezing" capabilities, making it dead simple to test time-dependent code.  It provides a unified method to mock Time.now, Date.today, and DateTime.now in a single call.
+test_files: 
+- test/test_timecop.rb
+- test/test_timecop_internals.rb
+- test/test_timecop_without_date.rb

data/Manifest.txt

@@ -1,14 +0,0 @@
-History.txt
-Manifest.txt
-README.txt
-Rakefile
-lib/timecop.rb
-lib/timecop/stack_item.rb
-lib/timecop/time_extensions.rb
-lib/timecop/timecop.rb
-lib/timecop/version.rb
-test/run_tests.sh
-test/test_timecop.rb
-test/test_timecop_internals.rb
-test/test_timecop_without_date.rb
-timecop.gemspec

data/README.textile

@@ -1,89 +0,0 @@
-h1. timecop
-
-* http://github.com/jtrupiano/timecop
-
-h2. DESCRIPTION
-
-A gem providing simple ways to mock Time.now, Date.today, and DateTime.now.  It provides "time travel" and "time freezing" capabilities, making it dead simple to test time-dependent code.
-
-h2. FEATURES
-
-* Temporarily (or permanently if you prefer) change the concept of Time.now, DateTime.now, and Date.today
-* Timecop api allows arguments to be passed into #freeze and #travel as one of the following:
-  # Time instance
-  # DateTime instance
-  # Date instance
-  # individual arguments (year, month, day, hour, minute, second)
-  # a single integer argument that is interpreted as an offset in seconds from Time.now
-  
-* Nested calls to Timecop#travel and Timecop#freeze are supported -- each block will maintain it's interpretation of now.
-
-h2. SHORTCOMINGS
-
-* Only fully tested on the 1.8.6 Ruby implementations.  1.8.7 and 1.9.1 should be tested, as well as other flavors (jruby, etc.)
-
-h2. SYNOPSIS
-
-* Run a time-sensitive test:
-<code>
-  joe = User.find(1)
-  joe.purchase_home()
-  assert !joe.mortgage_due?
-  # move ahead a month and assert that the mortgage is due
-  Timecop.freeze(Date.today + 30) do
-    assert joe.mortgage_due?
-  end
-</code>
-
-* Set the time for the test environment of a rails app -- this is particularly helpful if your whole application
-  is time-sensitive.  It allows you to build your test data at a single point in time, and to move in/out of that
-  time as appropriate (within your tests)
-  
-in config/environments/test.rb
-
-<code>
-config.after_initialize do
-  # Set Time.now to September 1, 2008 10:05:00 AM
-  t = Time.local(2008, 9, 1, 10, 5, 0)
-  Timecop.travel(t)
-end
-</code>
-
-h2. REQUIREMENTS
-
-* None
-
-h2. INSTALL
-
-* sudo gem install timecop (latest stable version from rubyforge)
-* sudo gem install jtrupiano-timecop (HEAD of the repo from github)
-
-h2. REFERENCES
-
-* http://blog.smartlogicsolutions.com/2008/11/19/timecop-freeze-time-in-ruby-for-better-testing/
-* http://blog.smartlogicsolutions.com/2008/12/24/timecop-2-released-freeze-and-rebase-time-ruby/
-
-h2. LICENSE
-
-(The MIT License)
-
-Copyright (c) 2008 FIX
-
-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/lib/timecop/version.rb

@@ -1,20 +0,0 @@
-module Timecop
-  module Version #:nodoc:
-    # A method for comparing versions of required modules. It expects two
-    # arrays of integers as parameters, the first being the minimum version
-    # required, and the second being the actual version available. It returns
-    # true if the actual version is at least equal to the required version.
-    def self.check(required, actual) #:nodoc:
-      required = required.map { |v| "%06d" % v }.join(".")
-      actual   = actual.map { |v| "%06d" % v }.join(".")
-      return actual >= required
-    end
-
-    MAJOR = 0
-    MINOR = 2
-    TINY  = 0
-
-    STRING = [MAJOR, MINOR, TINY].join(".")
-  end
-end
-