anticipate 0.0.1

data/README.rdoc

@@ -0,0 +1,26 @@
+= Anticipate
+
+== About
+
+Anticipate is a fluent interface for retrying blocks of code:
+  
+  trying_every(3).seconds.failing_after(9).tries do
+  
+    # Repeatedly calls block until it stops raising errors
+    
+  end
+  
+The Anticipate module allows the following expressions:
+
+  trying_every(n).seconds {}
+  failing_after(n).tries {}
+  trying_every(x).seconds.failing_after(y).tries {}
+  
+Blocks should contain an assertion, i.e. raise a
+descriptive error if some condition is unsatisfied. On
+the last iteration, the error will be wrapped in a
+TimeoutError and re-raised.
+
+I'm aware of a couple of gems supporting the
+begin-rescue-sleep-retry dance, namely 'retry' and 'attempt'.
+The aim of this library is to offer more expressive syntax.

data/anticipate.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require "anticipate"
+
+Gem::Specification.new do |s|
+  s.name        = 'anticipate'
+  s.version     = Anticipate::VERSION
+  s.authors     = ['Josh Chisholm']
+  s.description = 'Fluent interface for try-rescue-sleep-retry-abort'
+  s.summary     = "anticipate-#{s.version}"
+  s.email       = 'joshuachisholm@gmail.com'
+  s.homepage    = 'http://github.com/joshski/anticipate'
+
+  s.rubygems_version  = "1.3.7"
+  s.files             = `git ls-files`.split("\n")
+  s.test_files        = `git ls-files -- {spec}/*`.split("\n")
+  s.extra_rdoc_files  = ["README.rdoc"]
+  s.require_path      = "lib"
+end

data/lib/anticipate.rb

@@ -0,0 +1,74 @@
+lib = File.dirname(__FILE__)
+$:.unshift(lib) unless $:.include?(lib) || $:.include?(File.expand_path(lib))
+
+require 'anticipate/anticipator'
+
+module Anticipate
+  VERSION = '0.0.1'
+  
+  def anticipator
+    Anticipator.new(Kernel)
+  end  
+  
+  def default_tries
+    @default_tries ||= 1
+  end
+  
+  def default_interval
+    @default_interval ||= 0.1
+  end
+  
+  def trying_every(amount)
+    anticipation.trying_every(amount)
+  end
+  
+  def failing_after(amount)
+    anticipation.failing_after(amount)
+  end
+  
+  private
+  
+  def anticipation
+    Anticipation.new(anticipator, default_interval, default_tries)
+  end
+  
+  class Term
+    def initialize(anticipator, interval, timeout)
+      @anticipator, @interval, @timeout = anticipator, interval, timeout
+    end
+    
+    private
+    
+    def exec
+      @anticipator.anticipate(@interval, @timeout) do
+        yield
+      end
+    end
+    
+    def chain
+      Anticipation.new(@anticipator, @interval, @timeout)
+    end
+  end
+    
+  class TimeUnit < Term
+    def seconds
+      block_given? ? exec { yield } : chain
+    end
+  end
+  
+  class CountUnit < Term
+    def tries
+      block_given? ? exec { yield } : chain
+    end
+  end
+
+  class Anticipation < Term
+    def trying_every(amount)
+      TimeUnit.new(@anticipator, amount, @timeout)
+    end
+    
+    def failing_after(amount)
+      CountUnit.new(@anticipator, @interval, amount)
+    end
+  end
+end

data/lib/anticipate/anticipator.rb

@@ -0,0 +1,23 @@
+require 'anticipate/timeout_error'
+
+module Anticipate
+  class Anticipator
+    def initialize(sleeper)
+      @sleeper = sleeper
+    end
+  
+    def anticipate(interval, tries)
+      count = -1
+      begin
+        yield
+        return
+      rescue => e
+        if (count += 1) == tries
+          raise TimeoutError.new(interval, tries, e)
+        end
+        @sleeper.sleep interval
+        retry
+      end
+    end
+  end
+end

data/lib/anticipate/timeout_error.rb

@@ -0,0 +1,24 @@
+module Anticipate
+  class TimeoutError < RuntimeError
+    def initialize(interval, tries, last_error)
+      @interval, @tries, @last_error =
+        interval, tries, last_error
+    end
+    
+    def to_s
+      "Timed out after #{@tries} tries" +
+      " (tried every #{seconds(@interval)})" +
+      "\n#{@last_error}"
+    end
+    
+    def backtrace
+      @last_error.backtrace
+    end
+    
+    private
+    
+    def seconds(amount)
+      amount == 1 ? "1 second" : "#{amount} seconds"
+    end
+  end
+end

data/spec/anticipate/anticipate_spec.rb

@@ -0,0 +1,88 @@
+require 'spec_helper'
+
+module Anticipate
+  describe Anticipate do
+    include Anticipate
+    
+    before do
+      @anticipator = mock("anticipator")
+      @anticipator.stub!(:anticipate).and_yield
+    end
+    
+    def anticipator
+      @anticipator
+    end
+    
+    describe "trying_every(n).seconds" do
+      it "yields" do
+        called = false
+        trying_every(1).seconds { called = true }
+        called.should be_true
+      end
+      
+      it "overrides the interval" do
+        @anticipator.should_receive(:anticipate).with(55, anything)
+        trying_every(55).seconds {}
+      end
+      
+      it "uses the default timeout" do
+        @anticipator.should_receive(:anticipate).with(anything, default_tries)
+        trying_every(66).seconds {}
+      end
+    end
+    
+    describe "failing_after(n).tries" do
+      it "yields" do
+        called = false
+        failing_after(1).tries { called = true }
+        called.should be_true
+      end
+      
+      it "overrides the timeout" do
+        @anticipator.should_receive(:anticipate).with(anything, 77)
+        failing_after(77).tries {}
+      end
+      
+      it "uses the default interval" do
+        @anticipator.should_receive(:anticipate).with(default_interval, anything)
+        failing_after(88).tries {}
+      end
+    end
+    
+    describe "failing_after(x).tries.trying_every(y).seconds" do
+      it "yields" do
+        called = false
+        failing_after(2).tries.trying_every(1).seconds { called = true }
+        called.should be_true
+      end
+      
+      it "overrides the timeout" do
+        @anticipator.should_receive(:anticipate).with(anything, 222)
+        failing_after(222).tries.trying_every(111).seconds {}
+      end
+      
+      it "overrides the interval" do
+        @anticipator.should_receive(:anticipate).with(333, anything)
+        failing_after(444).tries.trying_every(333).seconds {}
+      end
+    end
+    
+    describe "trying_every(x).seconds.failing_after(y).tries" do
+      it "yields" do
+        called = false
+        trying_every(1).seconds.failing_after(2).tries { called = true }
+        called.should be_true
+      end
+      
+      it "overrides the timeout" do
+        @anticipator.should_receive(:anticipate).with(anything, 666)
+        trying_every(555).seconds.failing_after(666).tries {}
+      end
+      
+      it "overrides the interval" do
+        @anticipator.should_receive(:anticipate).with(777, anything)
+        trying_every(777).seconds.failing_after(888).tries {}
+      end
+    end
+  end
+end

data/spec/anticipate/anticipator_spec.rb

@@ -0,0 +1,66 @@
+require 'spec_helper'
+
+module Anticipate
+  describe Anticipator do
+    before do
+      @sleeper = mock("sleeper")
+      @sleeper.stub!(:sleep)
+      @anticipator = Anticipator.new(@sleeper)
+    end
+    
+    describe "#anticipate" do
+      
+      describe "when the block eventually stops raising" do
+        it "sleeps the given interval between tries" do
+          @sleeper.should_receive(:sleep).with(1).exactly(8).times
+          tries = 0
+          @anticipator.anticipate(1,9) do
+            raise "fail" unless (tries += 1) == 9
+          end
+          tries.should == 9
+        end
+        
+        it "does not raise" do
+          tries = 0
+          lambda {
+            @anticipator.anticipate(1,2) do
+              raise "fail" unless (tries += 1) == 2
+            end
+          }.should_not raise_error
+        end
+      end
+        
+      describe "when the block always raises" do
+        describe "when waiting for one second" do        
+          it "raises a TimeoutError, with the last error message" do
+            tries = 0
+            lambda {
+              @anticipator.anticipate(1,2) { raise (tries += 1).to_s }
+            }.should raise_error(TimeoutError,
+                      "Timed out after 2 tries (tried every 1 second)\n3")
+          end
+        end
+        
+        describe "when waiting for any other number of seconds" do
+          it "raises a TimeoutError, with the last error message" do
+            tries = 0
+            lambda {
+              @anticipator.anticipate(2,3) { raise (tries += 1).to_s }
+            }.should raise_error(TimeoutError,
+                      "Timed out after 3 tries (tried every 2 seconds)\n4")
+          end
+        end
+      end
+      
+      describe "when the block never raises" do
+        it "does not raise" do
+          lambda {
+            @anticipator.anticipate(1,2) do
+            end
+          }.should_not raise_error
+        end
+      end
+    end
+
+  end
+end

data/spec/anticipate/integration_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper'
+
+module Anticipate
+  describe Anticipate, "with default options" do
+    include Anticipate
+
+    it "raises when a block continually raises" do
+      raises = []
+      lambda {
+        trying_every(0.01).seconds.failing_after(5).tries {
+          raise (raises << Time.now).to_s
+        }
+      }.should raise_error(TimeoutError)
+      raises.size.should == 6
+      total_time = raises.last - raises.first
+      total_time.should > 0.05
+      total_time.should < 0.06
+    end
+
+    it "continues when a block stops raising" do
+      raises = 0
+      lambda {
+        trying_every(0.01).seconds.failing_after(3).tries {
+          raise (raises += 1).to_s unless raises == 2
+        }
+      }.should_not raise_error
+      raises.should == 2
+    end
+  end
+  
+  describe Anticipate, "with overridden tries" do
+    include Anticipate
+    
+    def default_tries
+      5
+    end
+
+    it "uses the overridden tries" do
+      raises = []
+      lambda {
+        trying_every(0.01).seconds {
+          raise (raises << Time.now).to_s
+        }
+      }.should raise_error(TimeoutError)
+      raises.size.should == 6
+      total_time = raises.last - raises.first
+      total_time.should > 0.05
+      total_time.should < 0.06
+    end
+  end
+  
+  describe Anticipate, "with overridden interval" do
+    include Anticipate
+    
+    def default_interval
+      0.01
+    end
+
+    it "uses the overridden interval" do
+      raises = []
+      lambda {
+        failing_after(5).tries {
+          raise (raises << Time.now).to_s
+        }
+      }.should raise_error(TimeoutError)
+      raises.size.should == 6
+      total_time = raises.last - raises.first
+      total_time.should > 0.05
+      total_time.should < 0.06
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+$:.unshift(File.dirname(__FILE__))
+
+require 'rubygems'
+require 'rspec'
+
+require File.dirname(__FILE__) + '/../lib/anticipate'

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: anticipate
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Josh Chisholm
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-31 00:00:00 +00:00
+default_executable: 
+dependencies: []
+
+description: Fluent interface for try-rescue-sleep-retry-abort
+email: joshuachisholm@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- anticipate.gemspec
+- lib/anticipate.rb
+- lib/anticipate/anticipator.rb
+- lib/anticipate/timeout_error.rb
+- spec/anticipate/anticipate_spec.rb
+- spec/anticipate/anticipator_spec.rb
+- spec/anticipate/integration_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/joshski/anticipate
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+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 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.4.1
+signing_key: 
+specification_version: 3
+summary: anticipate-0.0.1
+test_files: []
+