coffee_break 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 389dc9b0d377763ef61f9501dec4519620d27403
+  data.tar.gz: 8c35aa3c7630152482761965517cd75d11e55647
+SHA512:
+  metadata.gz: 577b11e440f1beb387ad15eeab849f417ea79d198755df2d35e3f0d6faa208cc8b80a67a4fb9e0a7457f6bbb360e5636ae33763b3e3cc8c2e0fb09121c054152
+  data.tar.gz: eda560c9cd0d74b48159b653041ffe8a020019eccc28bd159469153c031966901adb174b6a283d7c9c76618dab13fbf36a3595f4e196f8aa6c1bd4e00e77d076

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.11.2

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Cohen Carlisle
+
+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,97 @@
+# CoffeeBreak
+
+A gem to handle waiting until a condition is true.
+
+## About
+
+By default, CoffeeBreak calls the supplied block every 0.1 seconds while the
+result of calling the block is falsey. If the block returns a truthy value, that
+value is returned and program execution resumes. If the block isn't truthy
+before the default timeout period of 30 seconds, a `CoffeeBreak::TimeoutError`
+is raised.
+
+## Usage
+
+```ruby
+require 'coffee_break'
+include CoffeeBreak::Waiter
+
+Coffee.break.until { 2 + 2 }      # => returns 4
+Coffee.break.until { 2 + 2 == 4 } # => returns true
+Coffee.break.until { 2 + 2 == 5 } # => raises CoffeeBreak::TimeoutError
+```
+
+The timeout and time between block calls (interval) can be set in two ways:
+
+```ruby
+## Universal default
+CoffeeBreak.default_timeout = 5
+CoffeeBreak.default_interval = 0.1
+## One time setting
+Coffee.break(timeout: 5, interval: 0.1).until { foo }
+```
+
+Similarly, you can tell CoffeeBreak to rescue either one class of errors or an
+array of error classes that the block could raise.
+
+```ruby
+## Universal default
+CoffeeBreak.default_rescues = NameError
+# or CoffeeBreak.default_rescues = [ArgumentError, NoMethodError]
+## One time setting
+Coffee.break(rescues: [TypeError, ZeroDivisionError]).until { foo }
+# or Coffee.break(rescues: RuntimeError).until { foo }
+```
+
+You can also tell CoffeeBreak not to raise an error on timeout. Instead, the
+result of calling the block is returned.
+
+```ruby
+## Universal default
+CoffeeBreak.default_raise = false
+## One time setting
+Coffee.break(raise: false).until { falsey } # => returns false or nil
+```
+
+Finally, you can provide a message to be used if your block times out. If a
+`CoffeeBreak::TimeoutError` is raised, this will replace the default error
+message. If a timeout occurs but no error is raised (you set raise to `false`),
+the message will print as a warning (otherwise no warning is printed). This is
+only set in `until` (not `break`) and the universal default can't be changed.
+
+```ruby
+## One time setting
+Coffee.break.until(message: "foo couldn't bar") { foo.bar }
+```
+
+If you don't want `Coffee` in your top level namespace or don't like the above
+syntax, you can use the alternate syntax below. Note that `message` and the
+configuration arguments are all passed to `until`, unlike the above syntax which
+keeps your configuration and `message` arguments separate.
+
+```ruby
+CoffeeBreak.until(message: 'No yo', timeout: 5, raise: false) { Yo.yo? }
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to [rubygems.org]
+(https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/Cohen-Carlisle/coffee_break.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License]
+(http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "coffee_break"
+require "pry"
+
+include CoffeeBreak::Waiter
+
+pry

data/bin/setup

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/coffee_break.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'coffee_break/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "coffee_break"
+  spec.version       = CoffeeBreak::VERSION
+  spec.authors       = ["Cohen Carlisle"]
+  spec.email         = ["cohen.carlisle@gmail.com"]
+
+  spec.summary       = "A gem to handle waiting until a condition is true"
+  spec.homepage      = "https://github.com/Cohen-Carlisle/coffee_break"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "pry", "~> 0.10"
+end

data/lib/coffee_break.rb

@@ -0,0 +1,46 @@
+require "coffee_break/version"
+require "coffee_break/errors"
+require "coffee_break/default"
+require "coffee_break/waiter/coffee"
+
+module CoffeeBreak
+  def self.until(timeout: DEFAULT[:timeout], interval: DEFAULT[:interval],
+                 rescues: DEFAULT[:rescues], raise:    DEFAULT[:raise],
+                 message: nil,               &block)
+
+    Waiter::Coffee.break(timeout: timeout, interval: interval, rescues: rescues,
+                         raise: raise).until(message: message, &block)
+  end
+
+  def self.default_timeout
+    DEFAULT[:timeout]
+  end
+
+  def self.default_timeout=(seconds)
+    DEFAULT[:timeout] = seconds
+  end
+
+  def self.default_interval
+    DEFAULT[:interval]
+  end
+
+  def self.default_interval=(seconds)
+    DEFAULT[:interval] = seconds
+  end
+
+  def self.default_rescues
+    DEFAULT[:rescues]
+  end
+
+  def self.default_rescues=(exceptions)
+    DEFAULT[:rescues] = exceptions
+  end
+
+  def self.default_raise
+    DEFAULT[:raise]
+  end
+
+  def self.default_raise=(boolean)
+    DEFAULT[:raise] = boolean
+  end
+end

data/lib/coffee_break/default.rb

@@ -0,0 +1,9 @@
+module CoffeeBreak
+  # private
+  DEFAULT = {
+    timeout: 30,
+    interval: 0.1,
+    rescues: [],
+    raise: true
+  }
+end

data/lib/coffee_break/errors.rb

@@ -0,0 +1,3 @@
+module CoffeeBreak
+  class TimeoutError < RuntimeError; end
+end

data/lib/coffee_break/version.rb

@@ -0,0 +1,3 @@
+module CoffeeBreak
+  VERSION = "0.1.0"
+end

data/lib/coffee_break/waiter/coffee.rb

@@ -0,0 +1,38 @@
+module CoffeeBreak
+  module Waiter
+    class Coffee
+      def initialize(timeout: DEFAULT[:timeout], interval: DEFAULT[:interval],
+                     rescues: DEFAULT[:rescues], raise:    DEFAULT[:raise])
+
+        @timeout  = timeout
+        @interval = interval
+        @rescues  = rescues
+        @raise    = raise
+      end
+
+      class << self
+        alias break new
+      end
+
+      def until(message: nil)
+        result = nil
+        end_time = Time.now + @timeout
+        loop do
+          begin
+            result = yield
+            return result if result
+          rescue *@rescues
+          end
+          break if Time.now >= end_time
+          sleep @interval
+        end
+        if @raise
+          raise(TimeoutError, message || "Timed out after #{@timeout} seconds")
+        else
+          warn message if message
+          result
+        end
+      end
+    end
+  end
+end

data/spec/coffee_break_spec.rb

@@ -0,0 +1,185 @@
+require 'spec_helper'
+
+describe CoffeeBreak do
+  it 'has a version number' do
+    expect(CoffeeBreak::VERSION).not_to be nil
+  end
+
+  describe '#until' do
+    it 'can call Coffee::break and Coffee#until' do
+      break_args = {timeout: 9, interval: 8, rescues: 7, raise: 6}
+      until_args = {message: 5}
+      until_blok = -> { 4 }
+      coffee_obj = instance_double(Coffee)
+      expect(Coffee).to receive(:break).with(break_args).and_return(coffee_obj)
+      expect(coffee_obj).to receive(:until).with(until_args).and_yield
+      CoffeeBreak.until(break_args.merge(until_args), &until_blok)
+    end
+  end
+
+  context 'can set and get', reset: true do
+    it 'default_timeout' do
+      CoffeeBreak.default_timeout = 0.05
+      expect(CoffeeBreak.default_timeout).to eq 0.05
+      interval = CoffeeBreak.default_interval
+      time = Benchmark.measure { Coffee.break(raise: false).until { false } }
+      expect(time.real).to be_between(0.05, 0.05 + interval * 2)
+    end
+
+    it 'default_interval' do
+      CoffeeBreak.default_interval = 0.002
+      expect(CoffeeBreak.default_interval).to eq 0.002
+      timeout = CoffeeBreak.default_timeout
+      counter = 0
+      increment_counter = -> { counter += 1; false }
+      Coffee.break(raise: false).until(&increment_counter)
+      expect(counter).to eq(timeout / 0.002).or eq(timeout / 0.002 + 1)
+    end
+
+    it 'default_rescues with class argument' do
+      CoffeeBreak.default_rescues = ArgumentError
+      expect(CoffeeBreak.default_rescues).to eq ArgumentError
+      would_raise_argument_error = -> do
+        Coffee.break(raise: false).until { Object.new(1) }
+      end
+      expect(would_raise_argument_error).not_to raise_error
+    end
+
+    it 'default_rescues with array argument' do
+      CoffeeBreak.default_rescues = [ArgumentError, NoMethodError]
+      expect(CoffeeBreak.default_rescues).to eq [ArgumentError, NoMethodError]
+      would_raise_no_method_error = -> do
+        Coffee.break(raise: false).until { Object.new.potato }
+      end
+      expect(would_raise_no_method_error).not_to raise_error
+    end
+
+    it 'default_raise' do
+      CoffeeBreak.default_raise = false
+      expect(CoffeeBreak.default_raise).to eq false
+      would_raise_timeout_error = -> do
+        Coffee.break.until { 2 + 2 == 5 }
+      end
+      expect(would_raise_timeout_error).not_to raise_error
+    end
+  end
+
+  describe Coffee do
+    describe '::break' do
+      it 'can set the timeout' do
+        interval = CoffeeBreak.default_interval
+        coffee_break = Coffee.break(raise: false, timeout: 0.05)
+        time = Benchmark.measure { coffee_break.until { 2 + 2 == 5 } }
+        expect(time.real).to be_between(0.05, 0.05 + interval * 2)
+      end
+
+      it 'can set the interval' do
+        timeout = CoffeeBreak.default_timeout
+        counter = 0
+        increment_counter = -> { counter += 1; false }
+        Coffee.break(raise: false, interval: 0.002).until(&increment_counter)
+        expect(counter).to eq(timeout / 0.002).or eq(timeout / 0.002 + 1)
+      end
+
+      it 'can set the rescues with class argument' do
+        cb = Coffee.break(raise: false, rescues: ArgumentError)
+        would_raise_argument_error = -> do
+          cb.until { Object.new(1) }
+        end
+        expect(would_raise_argument_error).not_to raise_error
+      end
+
+      it 'can set the rescues with array argument' do
+        cb = Coffee.break(raise: false, rescues: [ArgumentError, NoMethodError])
+        would_raise_no_method_error = -> do
+          cb.until { Object.new.potato }
+        end
+        expect(would_raise_no_method_error).not_to raise_error
+      end
+
+      it 'can set the raise' do
+        would_raise_timeout_error = -> do
+          Coffee.break(raise: false).until { 2 + 2 == 5 }
+        end
+        expect(would_raise_timeout_error).not_to raise_error
+      end
+    end
+
+    describe '#until' do
+      context 'when the block evaluates to a truthy value' do
+        it 'returns the result' do
+          expect(Coffee.break.until { 2 + 2 == 4 }).to be true
+          expect(Coffee.break.until { 'truthy' }).to eq 'truthy'
+        end
+
+        it 'returns immediately' do
+          time = Benchmark.measure { Coffee.break(timeout: 1).until { true } }
+          expect(time.real).to be < 0.001
+        end
+
+        it 'evaluates the block at least once' do
+          counter = 0
+          expect(Coffee.break(timeout: -1).until { counter += 1 }).to eq 1
+          expect(counter).to eq 1
+        end
+      end
+
+      context 'when the block evaluates to a falsey value' do
+        it 'raises a TimeoutError with a default error message by default' do
+          error = CoffeeBreak::TimeoutError
+          message = "Timed out after #{CoffeeBreak::default_timeout} seconds"
+          with_falsey_block = -> { Coffee.break.until { 2 + 2 == 5 } }
+          expect(with_falsey_block).to raise_error(error, message)
+        end
+
+        it 'can report a custom error message when raise is true' do
+          custom_message = 'This is a custom message'
+          timeout = -> { Coffee.break.until(message: custom_message) { false } }
+          expect(timeout).to raise_error(custom_message)
+        end
+
+        it 'can warn with a custom message when raise is false' do
+          custom_message = 'This is a custom message'
+          timeout = -> do
+            Coffee.break(raise: false).until(message: custom_message) { false }
+          end
+          expect(timeout).to output(/#{custom_message}/).to_stderr
+        end
+
+        it 'does not warn by default' do
+          timeout = -> { Coffee.break(raise: false).until { false } }
+          expect(timeout).not_to output.to_stderr
+        end
+
+        it 'returns the result if configured not to raise error on timeout' do
+          coffee_break = Coffee.break(raise: false)
+          expect(coffee_break.until { 2 + 2 == 5 }).to be false
+          expect(coffee_break.until { nil }).to be nil
+        end
+
+        it 'continues evaluating the block until timeout' do
+          interval = CoffeeBreak.default_interval
+          coffee_break = Coffee.break(raise: false, timeout: 0.05)
+          time = Benchmark.measure { coffee_break.until { 2 + 2 == 5 } }
+          expect(time.real).to be_between(0.05, 0.05 + interval * 2)
+        end
+
+        it 'can rescue errors during wait and then raise TimeoutError' do
+          rescue_and_raise = -> do
+            Coffee.break(rescues: RuntimeError).until { raise }
+          end
+          expect(rescue_and_raise).to raise_error(CoffeeBreak::TimeoutError)
+        end
+
+        it 'evaluates the block at least once' do
+          counter = 0
+          negative_timer = -> do
+            Coffee.break(timeout: -1).until { counter += 1; false }
+          end
+          expect(negative_timer).to raise_error(CoffeeBreak::TimeoutError)
+          expect(counter).to eq 1
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'benchmark'
+require 'coffee_break'
+include CoffeeBreak::Waiter
+CoffeeBreak::DEFAULT[:interval] = 0.001
+CoffeeBreak::DEFAULT[:timeout]  = 0.01
+RSpec.configure do |config|
+  config.before(:example, reset: true) do
+    @defaults = CoffeeBreak::DEFAULT.dup
+  end
+
+  config.after(:example, reset: true) do
+    @defaults.each { |k,v| CoffeeBreak::DEFAULT[k] = v }
+  end
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: coffee_break
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Cohen Carlisle
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-01-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+description: 
+email:
+- cohen.carlisle@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- coffee_break.gemspec
+- lib/coffee_break.rb
+- lib/coffee_break/default.rb
+- lib/coffee_break/errors.rb
+- lib/coffee_break/version.rb
+- lib/coffee_break/waiter/coffee.rb
+- spec/coffee_break_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/Cohen-Carlisle/coffee_break
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: A gem to handle waiting until a condition is true
+test_files: []