retry_upto 1.0 → 1.1

data/README.md

@@ -1,44 +1,67 @@
 # retry_upto: retry with steroids
 
+If you need to use `retry` in ruby, you probably want to retry some code only a **maximum number of times**,
+and sometimes **wait a bit** between the attempts to avoid external resources hiccups or usage limits.
+
+Therefore **Your Important Code** ends surrounded by counters, conditions and calls to `sleep`.
+
+This gem deals elegantly with this common scenario:
+
+    5.times.retry do
+      # Your Important Code
+    end
+
+Keep reading to see all the options available.
+
 ## Usage
 
-Basic usage
+### Basic usage
 
-- retries up to 5 times catching any exception, doesn't wait between attempts:
+Retries up to 5 times catching any exception, doesn't wait between attempts:
 
-    retry_upto(5) do ... end
+    retry_upto(5)
 
-Waiting time between attempts
+### Waiting time between attempts
 
-- retries up to 5 times, waits 2 seconds between attempts:
+Retries up to 5 times, waits 2 seconds between attempts:
 
-   retry_upto(5, :interval => 2) do ... end
+    retry_upto(5, :interval => 2)
 
-Varying waiting time between attempts
+### Varying waiting time between attempts
 
-- retries up to 5 times, waits 1 second after the first attempt and increases
-  the time between the following attempts (2, 4, 8, ...):
+Retries up to 5 times, waits 1 second after the first attempt and increases
+the time between the following attempts (2, 4, 8, ...):
 
-    retry_upto(5, :interval => 1, :growth => 2) do ... end
+    retry_upto(5, :interval => 1, :growth => 2)
 
-- retries up to 5 times, waits 1 second after the first attempt and decreases
-  the time between the following attempts (0.5, 0.25, 0.125, ...):
+Retries up to 5 times, waits 1 second after the first attempt and decreases
+the time between the following attempts (0.5, 0.25, 0.125, ...):
 
-    retry_upto(5, :interval => 1, :growth => 0.5) do ... end
+    retry_upto(5, :interval => 1, :growth => 0.5)
 
-- retries up to 5 times, waits 1 second after the first attempt and increases
-  randomly the time between the following attempts:
+Retries up to 5 times, waits 1 second after the first attempt and increases
+randomly the time between the following attempts:
 
-    retry_upto(5, :interval => 1, :growth => lambda{ |x| x + rand(3) } ) do ... end
+    retry_upto(5, :interval => 1, :growth => lambda{ |x| x + rand(3) } )
 
-Retrying only when certain Exceptions get raised
+### Retrying only when certain Exceptions get raised
 
-- retries up to 5 times only after a ZeroDivisionError, raising any other Exception:
+Retries up to 5 times only after a ZeroDivisionError, raising any other Exception:
 
-    retry_upto(5, :rescue => ZeroDivisionError) do ... end
+    retry_upto(5, :rescue => ZeroDivisionError)
 
 All the options described above can be combined together.
 
+### More sugar!
+
+In ruby 1.9, the `Enumerator` class gets enhanced to use `retry_upto` this way:
+
+    5.times.retry
+
+And yes, this accepts the same options:
+
+    5.times.retry(:interval => 10)
+
 ## License
 
 See the LICENSE file included in the distribution.

data/lib/retry_upto.rb

@@ -1,49 +1,8 @@
-#  retry with steroids
-#
-#  Basic usage:
-#
-#  - retries up to 5 times catching any exception, doesn't wait between attempts
-#
-#      retry_upto(5) do ... end
-#
-#
-#  Waiting time between attempts:
-#
-#  - retries up to 5 times, waits 2 seconds between attempts
-#
-#     retry_upto(5, :interval => 2) do ... end
-#
-#
-#  Varying waiting time between attempts:
-#
-#  - retries up to 5 times, waits 1 second after the first attempt and increases
-#    the time between the following attempts (2, 4, 8, ...)
-#
-#      retry_upto(5, :interval => 1, :growth => 2) do ... end
-#
-#  - retries up to 5 times, waits 1 second after the first attempt and decreases
-#    the time between the following attempts (0.5, 0.25, 0.125, ...)
-#
-#      retry_upto(5, :interval => 1, :growth => 0.5) do ... end
-#
-#  - retries up to 5 times, waits 1 second after the first attempt and increases
-#    randomly the time between the following attempts
-#
-#      retry_upto(5, :interval => 1, :growth => lambda{ |x| x + rand(3) } ) do ... end
-#
-#
-#  Retrying only when certain Exceptions get raised:
-#
-#  - retries up to 5 times only after a ZeroDivisionError, raising any other Exception
-#
-#      retry_upto(5, :rescue => ZeroDivisionError) do ... end
-#
-#
-#  All the described options can be combined together.
+# See README.md for usage explanations
 
 def retry_upto(max_retries = 1, options = {})
   yield
-rescue (options[:rescue] || Exception)
+rescue *(options[:rescue] || Exception)
   raise if (max_retries -= 1) == 0
   sleep(options[:interval] || 0)
   if options[:growth].respond_to?('*')
@@ -54,15 +13,6 @@ rescue (options[:rescue] || Exception)
   retry
 end
 
-
-
-# Extends enumerator to allow usage like:
-#
-#    5.times.retry do
-#      ...
-#    end
-#
-
 class Enumerator
   def retry(options = {}, &blk)
     retry_upto(self.count, options, &blk)

data/test/retry_upto_test.rb

@@ -3,15 +3,25 @@ require './test/test_helper'
 class Retry_uptoTest < MiniTest::Unit::TestCase
 
   class FooError < Exception; end
+  class BarError < Exception; end
 
-  # raises ZeroDivisionError in the two first hits
   class Target
-    attr_accessor :hits
-    def initialize; @hits = 0; end
+    attr_accessor :foos, :bars
+    def initialize
+      @foos = 0
+      @bars = 0
+    end
+
+    # raises FooError only in the two first calls
+    def foo!
+      @foos += 1
+      raise FooError if @foos < 3
+    end
 
-    def hit!
-      @hits += 1
-      raise FooError if @hits < 3
+    # raises BarError only in the two first calls
+    def bar!
+      @bars += 1
+      raise BarError if @bars < 3
     end
   end
 
@@ -23,26 +33,26 @@ class Retry_uptoTest < MiniTest::Unit::TestCase
 
   def test_retries_one_time_by_default_without_capturing_the_exception
     assert_raises(FooError) do
-      retry_upto{ @target.hit! }
+      retry_upto{ @target.foo! }
     end
-    assert_equal 1, @target.hits
+    assert_equal 1, @target.foos
   end
 
   def test_retries_the_desired_number_of_attempts
-    retry_upto(3){ @target.hit! }
-    assert_equal 3, @target.hits
+    retry_upto(3){ @target.foo! }
+    assert_equal 3, @target.foos
   end
 
   # interval between attempts
 
   def test_there_is_no_interval_between_attempts_by_default
     self.expects(:sleep).times(2).with(0).returns(nil)
-    retry_upto(3){ @target.hit! }
+    retry_upto(3){ @target.foo! }
   end
 
   def test_interval_between_attempts_can_be_customized
     self.expects(:sleep).times(2).with(5).returns(nil)
-    retry_upto(3, :interval => 5){ @target.hit! }
+    retry_upto(3, :interval => 5){ @target.foo! }
   end
 
   # interval growth between attempts
@@ -50,42 +60,48 @@ class Retry_uptoTest < MiniTest::Unit::TestCase
   def test_inverval_can_be_multiplied_by_an_integer_growth
     self.expects(:sleep).times(1).with(5)
     self.expects(:sleep).times(1).with(15)
-    retry_upto(3, :interval => 5, :growth => 3){ @target.hit! }
+    retry_upto(3, :interval => 5, :growth => 3){ @target.foo! }
   end
 
   def test_grow_for_inverval_between_attempts_can_be_defined_with_a_lambda
     self.expects(:sleep).times(1).with(5)
     self.expects(:sleep).times(1).with(7)
-    retry_upto(3, :interval => 5, :growth => lambda{ |t| t + 2 }){ @target.hit! }
+    retry_upto(3, :interval => 5, :growth => lambda{ |t| t + 2 }){ @target.foo! }
   end
 
   # exceptions
 
   def test_by_default_any_exception_gets_captured_if_there_are_attempts_left
-    retry_upto(3){ @target.hit! }
+    retry_upto(3){ @target.foo! }
     assert true # if we reach this no exception was raised out of retry_upto
   end
 
   def test_the_last_attempt_does_not_capture_the_exception
     assert_raises(FooError) do
-      retry_upto(2){ @target.hit! }
+      retry_upto(2){ @target.foo! }
     end
   end
 
   def test_a_specified_exception_will_be_captured_between_attempts
-    retry_upto(3, :rescue => FooError){ @target.hit! }
+    retry_upto(3, :rescue => FooError){ @target.foo! }
+    assert true # if we reach this no exception was raised out of retry_upto
+  end
+
+  def test_several_specified_exceptions_will_be_captured_between_attempts
+    retry_upto(3, :rescue => [FooError, BarError]){ @target.foo! }
+    retry_upto(3, :rescue => [FooError, BarError]){ @target.bar! }
     assert true # if we reach this no exception was raised out of retry_upto
   end
 
   def test_the_last_attempt_does_not_capture_the_specified_exception
     assert_raises(FooError) do
-      retry_upto(2, :rescue => FooError){ @target.hit! }
+      retry_upto(2, :rescue => FooError){ @target.foo! }
     end
   end
 
   def test_a_exception_different_from_the_specified_one_will_not_be_captured_between_attempts
     assert_raises(FooError) do
-      retry_upto(3, :rescue => ZeroDivisionError){ @target.hit! }
+      retry_upto(3, :rescue => ZeroDivisionError){ @target.foo! }
     end
   end
 

metadata

@@ -1,84 +1,61 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: retry_upto
-version: !ruby/object:Gem::Version 
-  hash: 15
+version: !ruby/object:Gem::Version
+  version: '1.1'
   prerelease: 
-  segments: 
-  - 1
-  - 0
-  version: "1.0"
 platform: ruby
-authors: 
+authors:
 - Raul Murciano
 - Glenn Gillen
 - Pedro Belo
 - Jaime Iniesta
-- "Lle\xC3\xAFr Borras"
-- "Aitor Garc\xC3\xADa Rey"
+- Lleïr Borras
+- Aitor García Rey
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-10-07 00:00:00 -07:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-10-08 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: minitest
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2153033700 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">"
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 2
-        - 0
-        version: "2.0"
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '2.0'
   type: :development
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: mocha
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *2153033700
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: &2153033220 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 55
-        segments: 
-        - 0
-        - 10
-        - 0
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 0.10.0
   type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rake
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *2153033220
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &2153032760 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 63
-        segments: 
-        - 0
-        - 9
-        - 2
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 0.9.2
   type: :development
-  version_requirements: *id003
+  prerelease: false
+  version_requirements: *2153032760
 description: adds some useful options to retry code blocks
-email: 
+email:
 - raul@murciano.net
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - lib/retry_upto.rb
 - test/retry_upto_test.rb
 - test/test_helper.rb
@@ -87,39 +64,28 @@ files:
 - LICENSE
 - RakeFile
 - README.md
-has_rdoc: true
 homepage: http://github.com/raul/retry_upto
 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: retry_upto
-rubygems_version: 1.5.2
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: retry with steroids
 test_files: []
-