derring-do 1.0.0

data/README.markdown

@@ -0,0 +1,52 @@
+Derring-Do
+==========
+
+Derring-Do is a silly progress monitor that you can add to your console
+Ruby applications.
+
+It will emit "encouraging" words periodically, to indicate progress is being
+made on a job. If the campaign (or job) is given a target, the progress
+will also include updates saying specifically how far the campaign has gone
+toward that target.
+
+Usage
+-----
+
+    require 'derring-do'
+  
+    # untargetted campaigns (with no specifical goal in mind)
+  
+    derring do |campaign|
+      1000.times do
+        campaign.tally_ho!
+        sleep 0.2
+      end
+    end
+  
+    # targetted campaigns (aiming for a particular goal)
+  
+    derring do |campaign|
+      campaign.target = 2000
+      1000.times do
+        campaign.tally_ho! 2
+        sleep 0.2
+      end
+    end
+
+Installation
+------------
+
+    gem install derring-do
+
+Caveats
+-------
+
+I wrote this mostly to teach myself how to use rspec. The idea occurred to me
+while mostly asleep, so while it may not be actually useful, it is certainly
+whimsical.
+
+License
+-------
+
+This library is placed in the public domain by the author, Jamis Buck. Do
+with it what you will. Please prefer good over evil.

data/Rakefile

@@ -0,0 +1,26 @@
+require 'rake'
+require 'rake/gempackagetask'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+spec = Gem::Specification.new do |s|
+    s.platform = Gem::Platform::RUBY
+    s.summary = "The over-eager progress monitor."
+    s.name = 'derring-do'
+    s.version = "1.0.0"
+    s.add_development_dependency "rspec", "~> 2.1.0"
+    s.files = FileList["README.markdown", "Rakefile", "lib/**/*.rb", "spec/**/*.rb", "examples/**/*.rb"].to_a
+    s.description = "Derring-Do is a very eager progress monitor for console Ruby applications."
+    s.author = "Jamis Buck"
+    s.email = "jamis@jamisbuck.org"
+    s.homepage = "http://github.com/jamis/derring-do"
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+

data/examples/simple.rb

@@ -0,0 +1,8 @@
+require 'derring-do'
+
+derring do |campaign|
+  1000.times do
+    campaign.tally_ho!
+    sleep 0.02
+  end
+end

data/examples/targetted.rb

@@ -0,0 +1,9 @@
+require 'derring-do'
+
+derring do |campaign|
+  campaign.target = 2000
+  1000.times do
+    campaign.tally_ho! 2
+    sleep 0.02
+  end
+end

data/lib/derring-do.rb

@@ -0,0 +1,111 @@
+module DerringDo
+  @@configuration = { 
+    :update_wait_time => 5, # seconds
+    :minor_wait_time => 1,  # seconds
+    :output_to => STDOUT,   # where output is written
+  }
+
+  def self.configuration
+    @@configuration
+  end
+
+  class Campaign
+    attr_reader :progress
+    attr_accessor :target
+
+    def initialize
+      @progress = 0
+      @target = nil
+      @last_update_at = Time.now - DerringDo.configuration[:update_wait_time]
+      @last_minor_update_at = Time.now - DerringDo.configuration[:minor_wait_time]
+    end
+
+    def tally_ho!(n=1)
+      @progress += n
+      inform_if_ready
+    end
+
+    PANIC_WORDS = [
+      "Retreat!",
+      "Thomas Jefferson...still survives...",
+      "Nothing...but death.",
+      "Et tu, Brute?",
+      "I have tried so hard to do the right!",
+      "They couldn't hit an elephant at this dist--",
+    ]
+
+    def failed_with(error) #:nodoc:
+      panic = PANIC_WORDS[rand(PANIC_WORDS.length)]
+      DerringDo.configuration[:output_to].puts(panic)
+    end
+
+    INSULTS_ADJECTIVES = %w(yellow-bellied two-faced two-timing no-good spineless)
+    INSULTS_NOUNS = ["coward", "Benedict Arnold", "traitor", "wimp"]
+
+    def aborted! #:nodoc:
+      adj = INSULTS_ADJECTIVES.sort_by { rand }[0,3].join(", ")
+      noun = INSULTS_NOUNS[rand(INSULTS_NOUNS.length)]
+      DerringDo.configuration[:output_to].puts(adj + " " + noun + "!")
+    end
+
+    private
+
+    ENCOURAGING_WORDS = [
+      "Charge!",
+      "Into the breach!",
+      "Faugh a ballaugh!",
+      "Vive la Ruby!",
+      "Senta a pua!",
+    ]
+
+    CONGRATULATIONS = [
+      "Bob's yer uncle!",
+      "GADZOOKS!",
+      "Oh, I say! Well done!",
+      "Jolly good show!",
+      "By Jove! I think you've done it!",
+    ]
+
+    def inform_if_ready
+      now = Time.now
+
+      if target && progress >= target
+        word = CONGRATULATIONS[rand(CONGRATULATIONS.length)]
+        DerringDo.configuration[:output_to].puts(word)
+      elsif now - @last_update_at >= DerringDo.configuration[:update_wait_time]
+        @last_minor_update_at = @last_update_at = now
+        word = ENCOURAGING_WORDS[rand(ENCOURAGING_WORDS.length)]
+        DerringDo.configuration[:output_to].puts(word)
+      elsif target && now - @last_minor_update_at >= DerringDo.configuration[:minor_wait_time]
+        @last_minor_update_at = now
+        DerringDo.configuration[:output_to].puts "#{progress} / #{target}"
+      end
+    end
+  end
+
+  module Implementation
+    def derring
+      raise ArgumentError, "`derring' requires a block" unless block_given?
+
+      campaign = Campaign.new
+
+      begin
+        yield campaign
+      rescue Interrupt
+        campaign.aborted!
+        raise
+      rescue Exception => error
+        campaign.failed_with(error)
+        raise
+      end
+    end
+  end
+end
+
+class Object
+  if instance_methods.any? { |i| i.to_sym == :derring }
+    warn "Object#derring is already present; the `derring-do' gem may behave oddly."
+  end
+
+  include DerringDo::Implementation
+end

data/spec/derring_spec.rb

@@ -0,0 +1,142 @@
+require 'derring-do'
+require 'stringio'
+
+class Interrupted < RuntimeError; end
+trap("INT") { raise Interrupted }
+
+describe "derring" do
+  before(:each) do
+    @io = StringIO.new
+    DerringDo.configuration[:output_to] = @io
+    DerringDo.configuration[:update_wait_time] = 5
+    DerringDo.configuration[:minor_wait_time] = 1
+  end
+
+  context "without a block" do
+    it "raises an exception" do
+      expect{derring}.to raise_error(ArgumentError)
+    end
+  end
+
+  context "with no target" do
+    it "provides a campaign to the block" do
+      called = false
+
+      derring do |campaign|
+        called = true
+        campaign.should_not == nil
+      end
+
+      called.should == true
+    end
+
+    it "increments progress when tally_ho! is called on the campaign" do
+      derring do |campaign|
+        expect{campaign.tally_ho!}.to change{campaign.progress}.from(0).to(1)
+      end
+    end
+
+    it "shouts encouragement initially" do
+      derring do |campaign|
+        expect{campaign.tally_ho!}.to change{@io.string.length}
+      end
+    end
+
+    it "shouts encouragement when time has elapsed" do
+      DerringDo.configuration[:update_wait_time] = 0.5
+
+      derring do |campaign|
+        campaign.tally_ho!
+        expect{campaign.tally_ho!}.to_not change{@io.string.length}
+        sleep 0.5
+        expect{campaign.tally_ho!}.to change{@io.string.length}
+      end
+    end
+  end
+
+  context "with a target" do
+    it "provides a campaign to the block" do
+      called = false
+
+      derring do |campaign|
+        called = true
+        campaign.should_not == nil
+        campaign.target = 100
+        campaign.target.should == 100
+      end
+
+      called.should == true
+    end
+
+    it "increments progress when tally_ho! is called on the campaign" do
+      derring do |campaign|
+        campaign.target = 100
+        expect{campaign.tally_ho!}.to change{campaign.progress}.from(0).to(1)
+      end
+    end
+
+    it "moves toward completion when tally_ho!(n) is called on the campaign" do
+      derring do |campaign|
+        campaign.target = 100
+        expect{campaign.tally_ho! 5}.to change{campaign.progress}.from(0).to(5)
+      end
+    end
+
+    it "displays progress when some time has elapsed" do
+      DerringDo.configuration[:minor_wait_time] = 0.1
+
+      derring do |campaign|
+        campaign.target = 100
+        expect{campaign.tally_ho! 5}.to change{@io.string.length}
+        expect{campaign.tally_ho! 5}.to_not change{@io.string.length}
+        sleep 0.1
+        expect{campaign.tally_ho! 5}.to change{@io.string.length}
+      end
+    end
+
+    it "only shouts encouragement when more time has elapsed" do
+      DerringDo.configuration[:minor_wait_time] = 5
+      DerringDo.configuration[:update_wait_time] = 0.1
+
+      derring do |campaign|
+        campaign.target = 100
+        expect{campaign.tally_ho! 5}.to change{@io.string.length}
+        expect{campaign.tally_ho! 5}.to_not change{@io.string.length}
+        sleep 0.1
+        expect{campaign.tally_ho! 5}.to change{@io.string.length}
+      end
+    end
+
+    it "shouts congratulations when the target is achieved" do
+      derring do |campaign|
+        campaign.target = 100
+        expect{campaign.tally_ho! 5}.to change{@io.string.length}
+        expect{campaign.tally_ho! 95}.to change{@io.string.length}
+      end
+    end
+  end
+
+  context "when an error occurs" do
+    it "shouts a panicked exclamation" do
+      expect do
+        expect do
+          derring do |campaign|
+            raise "ouch!"
+          end
+        end.to raise_error(RuntimeError)
+      end.to change{@io.string.length}
+    end
+  end
+
+  context "when aborted" do
+    it "shouts insults" do
+      expect do
+        expect do
+          derring do |campaign|
+            Process.kill("INT", $$)
+          end
+        end.to raise_error(Interrupted)
+      end.to change{@io.string.length}
+    end
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification 
+name: derring-do
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Jamis Buck
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-13 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 2
+        - 1
+        - 0
+        version: 2.1.0
+  type: :development
+  version_requirements: *id001
+description: Derring-Do is a very eager progress monitor for console Ruby applications.
+email: jamis@jamisbuck.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.markdown
+- Rakefile
+- lib/derring-do.rb
+- spec/derring_spec.rb
+- examples/simple.rb
+- examples/targetted.rb
+has_rdoc: true
+homepage: http://github.com/jamis/derring-do
+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.3.7
+signing_key: 
+specification_version: 3
+summary: The over-eager progress monitor.
+test_files: []
+