goran 0.5 → 0.6

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Nitesh
+
+MIT License
+
+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.md

@@ -0,0 +1,84 @@
+# Goran
+
+Named after Goran Invanisevic, the tennis legend who won the Wimbledon after losing the final 3 times, Goran provides a simple syntax to run a block of code multiple times. E.g.
+    
+* run block 'x' number of times
+* run until the block returns a non-nil value
+* run until the block does not raise an exception
+* run until the block returns a non-zero value, to a maximum of 3 times, and return nil if all runs return a 0
+    
+Goran is especially useful for running network calls which have unexpected outputs like 404, timeouts. It is an easy way to build in retry logic into these calls and handle cases where these calls do not succeed at all.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'goran'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install goran
+
+## Usage
+
+	require 'goran'
+	
+Run a block until it stops returning `0`
+	
+	Goran.serve :retry_if => 0 do
+	  #block
+	end
+
+Run a block until it returns a value > 0; run it a maximum of 3 times
+	
+	Goran.serve :max_tries => 3, :retry_if => { |x| x <= 0 } do
+	  #block
+	end
+	
+Run a block until it stops returning `0`; run it a maximum of 3 times; wait for a second between calls
+	
+	Goran.serve :max_tries => 3, :retry_if => 0, :interval => 1 do
+	  #block
+	end	
+	
+Run a block until it stops returning `0`; run it a maximum of 3 times; return `nil` if it doesn't return a non-zero value even after 3 tries
+
+	Goran.serve :max_tries => 3, :retry_if => 0, :fallback => nil do
+	  #block
+	end
+
+Run a block until it doesn't raise a `StandardError`
+
+	Goran.serve :rescue_from => StandardError do
+	  #block
+	end
+
+Run a block until it doesn't raise a `StandardError`; run it a maximum of 3 times; supress error all three times
+
+	Goran.serve :max_tries => 3, :rescue_from => StandardError do
+	  #block
+	end
+	
+Run a block until it doesn't raise a `StandardError`; run it a maximum of 3 times; do not supress an error in the last run
+
+	Goran.serve :max_tries => 3, :rescue_from => StandardError, :rescue_last => false
+	  #block
+	end
+
+Run a block until it doesn't raise a `StandardError`; run it a maximum of 3 times; run a block when an error happens (say for logging the error)
+
+	Goran.serve :max_tries => 3, :rescue_from => StandardError, :on_rescue => lambda { |e| logger.error e }
+	  #block
+	end
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/goran.rb

@@ -0,0 +1,47 @@
+require "goran/version"
+
+module Goran
+  def self.serve(options)
+    # set max tries to infinity if none is given
+    max_tries = options[:max_tries] || 1.0/0
+    # if no retry is given, assume that the caller is just retrying to
+    # handle exceptions. hence, make sure it always returns false.
+    retry_if = if options.has_key?(:retry_if) then options[:retry_if] else lambda { |x| false } end
+    # set fallback value only if a fallback is defined
+    fallback = options[:fallback] if options.has_key?(:fallback)
+    # set exceptions to rescue from. set to fake exception if none provided
+    rescue_from = options[:rescue_from] || Goran::DoubleFault
+    # should the last exception in the iteration be rescued from?
+    rescue_last = options[:rescue_last] != false
+    # what do do on rescue
+    on_rescue = options[:on_rescue]
+    # time between successive calls.
+    interval = options[:interval] || 0
+    
+    result = nil
+    1.upto(max_tries) do |i|
+      begin
+        result = yield
+        if retry_if.kind_of?(Proc)
+          break unless retry_if.call(result)
+        elsif retry_if != result
+          break
+        end
+        # the flow should not come here if the result was good
+        result = fallback if options.has_key?(:fallback)
+      rescue *rescue_from => e
+        if i == max_tries && !rescue_last
+          raise e
+        else
+          result = fallback if options.has_key?(:fallback)
+          on_rescue.call(e) if on_rescue.kind_of?(Proc)
+        end
+      ensure
+        sleep interval unless interval.zero?
+      end
+    end
+    result
+  end
+  
+  class DoubleFault < StandardError; end
+end

data/lib/goran/version.rb

@@ -0,0 +1,3 @@
+module Goran
+  VERSION = '0.6'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: goran
 version: !ruby/object:Gem::Version
-  version: '0.5'
+  version: '0.6'
   prerelease: 
 platform: ruby
 authors:
@@ -26,6 +26,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
+- Rakefile
+- LICENSE
+- lib/goran/version.rb
+- lib/goran.rb
 - spec/goran_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/wallwisher/goran