Merge remote-tracking branch 'jduff/add_safe_mode'

* jduff/add_safe_mode:
  change method from safe_mode to safe_mode?
  Add documentation
  Change the SafeModeException to StandardError
  Add safe mode option which forces use of blocks with the method calls

Conflicts:
	test/timecop_test.rb

README.markdown

@@ -111,6 +111,23 @@ Time.now
 # => 2012-09-21 06:22:59 -0500
 ```
 
+### Timecop.safe_mode
+
+Safe mode forces you to use Timecop with the block syntax since it always puts time back the way it was. If you are running in safe mode and use Timecop without the block syntax `Timecop::SafeModeException` will be raised to tell the user they are not being safe.
+
+``` ruby
+# turn on safe mode
+Timecop.safe_mode = true
+
+# check if you are in safe mode
+Timecop.safe_mode?
+# => true
+
+# using method without block
+Timecop.freeze
+# => Timecop::SafeModeException: Safe mode is enabled, only calls passing a block are allowed.
+```
+
 See #42 for more information, thanks to Ken Mayer, David Holcomb, and Pivotal Labs.
 
 ## Contribute

lib/timecop/timecop.rb

@@ -102,6 +102,14 @@ def top_stack_item #:nodoc:
       instance.instance_variable_get(:@_stack).last
     end
 
+    def safe_mode=(safe)
+      @safe_mode = safe
+    end
+
+    def safe_mode?
+      false || @safe_mode
+    end
+
     private
     def send_travel(mock_type, *args, &block)
       val = instance.send(:travel, mock_type, *args, &block)
@@ -121,6 +129,8 @@ def initialize #:nodoc:
   end
 
   def travel(mock_type, *args, &block) #:nodoc:
+    raise SafeModeException if Timecop.safe_mode? && !block_given?
+
     stack_item = TimeStackItem.new(mock_type, *args)
 
     stack_backup = @_stack.dup
@@ -156,4 +166,10 @@ def return_to_baseline
       unmock!
     end
   end
+
+  class SafeModeException < StandardError
+    def initialize
+      super "Safe mode is enabled, only calls passing a block are allowed."
+    end
+  end
 end

test/timecop_test.rb

@@ -459,4 +459,37 @@ def test_datetime_to_time_for_dst_to_non_dst
     end
   end
 
+  def test_raises_when_safe_mode_and_no_block
+    with_safe_mode do
+      assert_raise Timecop::SafeModeException do
+        Timecop.freeze
+      end
+    end
+  end
+
+  def test_no_raise_when_safe_mode_and_block_used
+    with_safe_mode do
+      assert_nothing_raised do
+        Timecop.freeze {}
+      end
+    end
+  end
+
+  def test_no_raise_when_not_safe_mode_and_no_block
+    with_safe_mode(false) do
+      assert_nothing_raised do
+        Timecop.freeze
+      end
+    end
+  end
+
+  private
+
+  def with_safe_mode(enabled=true)
+    mode = Timecop.safe_mode?
+    Timecop.safe_mode = enabled
+    yield
+  ensure
+    Timecop.safe_mode = mode
+  end
 end