stephencelis-dots 0.0.1

data/History.rdoc

@@ -0,0 +1,5 @@
+== 0.0.1 / 2009-05-10
+
+* 1 major enhancement:
+
+  * Birthday!

data/Manifest.txt

@@ -0,0 +1,16 @@
+History.rdoc
+Manifest.txt
+Rakefile
+README.rdoc
+cucumber.yml
+dots.gemspec
+features
+features/dots.feature
+features/step_definitions/dots_steps.rb
+features/support/env.rb
+lib
+lib/dots/kaoemoji.rb
+lib/dots/rainbows.rb
+lib/dots/redgreen.rb
+lib/dots.rb
+spec/dots_spec.rb

data/README.rdoc

@@ -0,0 +1,89 @@
+  RDoc.......................................................................
+  ........................FFF................FFF.........F...................
+  ........................FF.................FF...........E..................
+  ..................FFFFF.FF....FFFFFF....FEFFFEF...FEEFFEE..................
+  ................FF....FFFF...FE....FFF....FFF....FEF.......................
+  ................FFF....FFF...FEF....FF.....FF......FFEEF...................
+  ..................FEEEF.FFF....EEEEEF.......FEF........FFF.................
+  ...................................................FFEEFF..................
+  ................FFFFFEEEEEFFFFF.F..F.FFFFFEEEEEEFFFFF......................
+  ..............F........F.FFFFEEEEEEEEEEFFFFF.F.............................
+  .....................................................................ready!
+
+Free progress dots for your scripts. <tt>Test::Unit</tt>-style.
+
+http://github.com/stephencelis/dots
+
+
+== Example
+
+  % ruby -rubygems
+  require "dots"
+  require "open-uri"
+  require "hpricot"
+
+  File.open("alts.txt", "w") do |f|
+    (1..10).each.with_dots do |n|
+      doc = Hpricot open("http://www.qwantz.com/archive/%06d.html" % n)
+      alt = (doc / "font img").pop["title"]
+      raise "No alt text found!" if alt.nil?
+      f.puts "%3d. %s" % [n, alt]
+    end
+  end
+  ^D
+  ..........
+  Finished in 6.225932 seconds.
+
+  10 total, 10 passed, 0 failed, 0 erred
+
+
+== Usage
+
+Swap out +each+ for +each_with_dots+, or, with enumerators, just add
++with_dots+; if you don't want to write to standard output, specify the IO as
+an argument for +each_with_dots+ (or +with_dots+).
+
+Raise nameless (i.e., +RuntimeError+) exceptions for potential failures.
+
+
+== Extras
+
+* <tt>require "dots/redgreen"</tt>
+* <tt>require "dots/rainbows"</tt>
+* <tt>require "dots/kaoemoji"</tt>
+
+Oh, and for heavy, non-iterative processing:
+
+  dots do
+    # ...
+  end
+
+
+== Install
+
+  % sudo gem install stephencelis-dots --source=http://gems.github.com
+
+
+== License
+
+(The MIT License)
+
+(c) 2009-* Stephen Celis, stephen@stephencelis.com.
+
+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/Rakefile

@@ -0,0 +1,40 @@
+defaults = [:requirements]
+required = []
+required << "* Ruby 1.8.7 or greater is required" if RUBY_VERSION < "1.8.7"
+
+desc "Show any uninstalled requirements to run the full test suite"
+task :requirements do
+  puts required
+end
+
+begin
+  require "spec/rake/spectask"
+
+  desc "Run all specs"
+  Spec::Rake::SpecTask.new :spec do |t|
+    t.ruby_opts = ["-Ilib"]
+    t.spec_opts = ["--color"]
+    t.spec_files = FileList["spec/**/*_spec.rb"]
+  end
+
+  defaults << :spec
+rescue LoadError
+  required << "* RSpec is required."
+end
+
+begin
+  require "cucumber/rake/task"
+
+  desc "Run all features"
+  Cucumber::Rake::Task.new :features do |t|
+    t.cucumber_opts = "--no-source --format=progress features"
+  end
+
+  defaults << :features
+rescue LoadError
+  required << "* Cucumber is required"
+end
+
+defaults << :requirements if defaults.empty?
+
+task :default => defaults

data/cucumber.yml

@@ -0,0 +1 @@
+default: --no-source features

data/dots.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{dots}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Stephen Celis"]
+  s.date = %q{2009-05-10}
+  s.description = %q{Free progress dots for your scripts.}
+  s.email = ["stephen@stephencelis.com"]
+  s.extra_rdoc_files = ["History.rdoc", "Manifest.txt", "README.rdoc"]
+  s.files = ["History.rdoc", "Manifest.txt", "Rakefile", "README.rdoc", "cucumber.yml", "dots.gemspec", "features", "features/dots.feature", "features/step_definitions/dots_steps.rb", "features/support/env.rb", "lib", "lib/dots/kaoemoji.rb", "lib/dots/rainbows.rb", "lib/dots/redgreen.rb", "lib/dots.rb", "spec/dots_spec.rb"]
+  s.has_rdoc = true
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{dots}
+  s.rubygems_version = %q{1.3.2}
+  s.summary = %q{Free progress dots for your scripts}
+  s.homepage = "http://github.com/stephencelis/dots"
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+  end
+end

data/features/dots.feature

@@ -0,0 +1,49 @@
+Feature: dot progress
+  In order to keep track of long-running tasks
+  As a task-runner
+  I want to see the progress visually
+
+  Scenario: Display dots
+    Given an array [1, 2, 3, 4, 5]
+    When I run it with dots
+    Then I should see 5 "." dots
+    And I should see 0 "F" dots
+    And I should see 0 "E" dots
+    And I should see how long it took
+    And I should not see "Failure"
+    And I should not see "Error"
+    And I should see "5 total, 5 passed, 0 failed, 0 erred"
+
+  Scenario: Display failures
+    Given an array [1, 2, 3, 4, 5]
+    When I don't want 3s
+    And I run it with dots
+    Then I should see 4 "." dots
+    And I should see 1 "F" dot
+    And I should see 0 "E" dots
+    And I should see how long it took
+    And I should see ") Failure" 1 time
+    And I should not see ") Error"
+    And I should see "No threes!"
+    And I should see the exception's line number
+    And I should see "<3>"
+    And I should see "5 total, 4 passed, 1 failed, 0 erred"
+  
+  Scenario: Display errors
+    Given an array [1, 2, 3, 4, 5]
+    When I divide each by zero
+    And I run it with dots
+    Then I should see 5 "E" dots
+    And I should see 0 "." dots
+    And I should see 0 "F" dots
+    And I should see how long it took
+    And I should see ") Error" 5 times
+    And I should see "ZeroDivisionError: divided by 0" 5 times
+    And I should see the exception's line number
+    And I should not see "Failure"
+    And I should see "5 total, 0 passed, 0 failed, 5 erred"
+
+  Scenario: Constant dots
+    Given a task that takes 5 seconds
+    When I run it in a dots block
+    Then I should see 5 "." dots

data/features/step_definitions/dots_steps.rb

@@ -0,0 +1,59 @@
+Given(/^an \w+ (.+)$/) do |object|
+  @enumerable = eval(object)
+end
+
+Given(/^a task that takes (\d+) seconds$/) do |number|
+  short_second  = 1 / 100
+  short_seconds = number.to_i / 100
+  @proc = Proc.new { |io| dots(short_second, io) { sleep short_seconds } }
+end
+
+When(/^I run it with dots$/) do
+  @proc ||= Proc.new { |each| each }
+  @io = StringIO.new
+  @enumerable.each_with_dots(@io, &@proc)
+  @io.rewind
+  @content = @io.read
+end
+
+When(/^I run it in a dots block$/) do
+  @io = StringIO.new ""
+  @proc.call(@io)
+  @io.rewind
+  @content = @io.read
+end
+
+When(/^I don't want (\d+)s$/) do |number|
+  @proc = Proc.new { |each| raise "No threes!" if each == number.to_i }
+  @line = __LINE__ - 1
+end
+
+When(/^I divide each by zero$/) do
+  @proc = Proc.new { |each| each / 0 }
+  @line = __LINE__ - 1
+end
+
+Then(/^I should see (\d+) "([^\"])" dots?$/) do |dot, number|
+  length = @enumerable.nil? ? -1 : @enumerable.length
+  @content[0..length].count(dot).should be(number.to_i)
+end
+
+Then(/^I should see how long it took$/) do
+  @content.should match(/Finished in \d+\.\d+ seconds/)
+end
+
+Then(/^I should see "([^\"]*)" (\d+) times?$/) do |message, number|
+  @content.split(message).length.should be(number.to_i + 1)
+end
+
+Then(/^I should see "([^\"]*)"$/) do |message|
+  @content.should include(message)
+end
+
+Then(/^I should not see "([^\"]*)"$/) do |message|
+  @content.should_not include(message)
+end
+
+Then(/^I should see the exception's line number$/) do
+  @content.should include("#{File.basename(__FILE__)}:#@line")
+end

data/features/support/env.rb

@@ -0,0 +1,4 @@
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + "/../../lib")
+require "dots"
+require "spec/expectations"
+require "spec/mocks"

data/lib/dots.rb

@@ -0,0 +1,169 @@
+# Dots makes dots.
+module Dots
+  VERSION = "0.0.1"
+
+  class InvalidDot < StandardError
+  end
+
+  #--
+  # Allows us direct access to +Enumerator+, ensuring compatibility with 1.8.7
+  # and 1.9.
+  #++
+  include Enumerable
+
+  #--
+  # How dots appear.
+  #++
+  @@dots = { "." => ".", "F" => "F", "E" => "E" }
+
+  # Access how a dot should appear.
+  def [](key)
+    raise InvalidDot unless @@dots.keys.include? key.to_s
+    dot = @@dots[key.to_s]
+    dot.respond_to?(:call) ? dot.call : dot
+  end
+
+  # Configure how dots appear. For red and green:
+  #
+  #   Dots["."] = "\e[32m.\e[0m"
+  #   Dots["F"] = "\e[31mF\e[0m"
+  #   Dots["E"] = "\e[31mE\e[0m"
+  #
+  # Or, just <tt>require "dots/redgreen"</tt>.
+  #
+  # For a random rainbow, <tt>require "dots/rainbow"</tt>, or use a procedure:
+  #
+  #   Dots["."] = Proc.new { \e[%dm.\e[0m" % [rand(10) + 30] }
+  def []=(key, value)
+    raise InvalidDot unless @@dots.keys.include? key.to_s
+    @@dots[key.to_s] = value
+  end
+
+  Enumerable.module_eval do
+    # Sends a dot to standard output (or designated IO) after each iteration.
+    #
+    # If an exception is raised during an iteration, an "E" or "F" will be
+    # sent in dot's stead: "F" for instances of +RuntimeError+, which may be
+    # raised blankly in an iteration, and "E" otherwise, assuming
+    # unanticipated errors.
+    #
+    # Example:
+    #
+    #   >> require "dots"
+    #   => true
+    #   >> (0..5).each_with_dots do |n|
+    #   ?>   100 / n
+    #   ?>   raise "No fours!" if n == 4
+    #   ?> end
+    #   E...F.
+    #   Finished in 0.000430 seconds.
+    # 
+    #     1) Error
+    #   ZeroDivisionError: divided by 0
+    #   with <0>
+    #     (irb):3:in `/'
+    #     (irb):3:in `irb_binding'
+    #     (irb):2:in `irb_binding'
+    #     /usr/local/lib/ruby/1.8/irb/workspace.rb:52:in `irb_binding'
+    #     /usr/local/lib/ruby/1.8/irb/workspace.rb:52
+    # 
+    #     2) Failure
+    #   No fours! 
+    #   with <4>
+    #   [(irb):4]
+    def each_with_dots(io = $stdout)
+      old_sync, io.sync = io.sync, true
+      exceptions, passed, start = [], 0, Time.now
+      trap("INT") { return io.puts "abort!" }
+      each do |object|
+        begin
+          yield object
+          io.print Dots["."]
+          passed += 1
+        rescue => e
+          if e.is_a? RuntimeError
+            io.print Dots["F"]
+          else
+            io.print Dots["E"]
+          end
+          exceptions << [object, e] unless exceptions.nil?
+        end
+      end
+    ensure
+      Dots.report exceptions, passed, start, io
+      io.sync = old_sync
+    end
+  end
+
+  Enumerator.class_eval do
+    # Returns an <tt>Enumerator</tt> for <tt>Enumerable#each_with_dots</tt>.
+    def with_dots(io = $stdout, &block)
+      enum = enum_for :each_with_dots, io
+      block_given? ? enum.each(&block) : enum
+    end
+  end if RUBY_VERSION >= "1.8.7"
+
+  Kernel.module_eval do
+    private
+    # Sends dots to standard output (or designated IO) on an interval for the
+    # duration of the block.
+    #
+    # Example:
+    #
+    #   >> dots do
+    #   ?>   sleep 5
+    #   ?> end
+    #   .....=> 5
+    def dots(interval = 1, io = $stdout)
+      old_sync, io.sync = io.sync, true 
+
+      thread = Thread.new do
+        dot = lambda do
+          io.print Dots["."]
+          sleep interval and dot.call
+        end
+        dot.call
+      end
+
+      yield
+    ensure
+      io.sync = old_sync
+      thread.kill
+    end
+  end
+
+  # Formats reports for +each_with_dots+.
+  def report(exceptions, passed = 0, start = nil, io = $stdout)
+    failed = erred = 0
+
+    io.puts
+    io.puts "Finished in #{Time.now - start} seconds." unless start.nil?
+    exceptions.each_with_index do |(o, e), i|
+      io.puts
+      if e.is_a? RuntimeError
+        failed += 1
+        io.puts "%3d) Failure" % [i + 1]
+        io.puts "#{e.message} " unless e.message.empty?
+        io.puts "with <#{o.inspect}>"
+        io.puts "[#{e.backtrace.first[/.+\d+/]}]"
+      else
+        erred += 1
+        io.puts "%3d) Error" % [i + 1]
+        io.puts "#{e.class.name}: #{e.message}"
+        io.puts "with <#{o.inspect}>"
+        io.puts e.backtrace.select { |l| l !~ /dots.rb/ }.map { |l| "\t#{l}" }
+      end
+    end
+    io.puts
+    io.puts summary(passed, failed, erred)
+  end
+
+  private
+
+  def summary(passed, failed, erred)
+    "%d total, %d passed, %d failed, %d erred" %
+      [passed + failed + erred, passed, failed, erred]
+  end
+
+  extend self
+end

data/lib/dots/kaoemoji.rb

@@ -0,0 +1,5 @@
+# Require this file to give your iterations some personality.
+
+Dots["."] = "\e[32m(^_^)\e[0m"
+Dots["F"] = "\e[31m(>_<)\e[0m"
+Dots["E"] = "\e[34m(T_T)\e[0m"

data/lib/dots/rainbows.rb

@@ -0,0 +1,5 @@
+# Require this file to add some capricious playfulness to your iterations.
+
+Dots["."] = Proc.new { "\e[%dm.\e[0m" % [rand(10) + 30] }
+Dots["F"] = Proc.new { "\e[%dmF\e[0m" % [rand(10) + 30] }
+Dots["E"] = Proc.new { "\e[%dmE\e[0m" % [rand(10) + 30] }

data/lib/dots/redgreen.rb

@@ -0,0 +1,14 @@
+# Require this file to add some red and green flair to your iterations.
+
+Dots["."] = "\e[32m#{Dots["."]}\e[0m"
+Dots["F"] = "\e[31m#{Dots["F"]}\e[0m"
+Dots["E"] = "\e[31m#{Dots["E"]}\e[0m"
+
+Dots.module_eval do
+  # Overrides Dots#summary with some red and green flair.
+  def summary(passed, failed, erred)
+    code = failed + erred == 0 ? "2" : "1"
+    "\e[3%dm%d total, %d passed, %d failed, %d erred\e[0m" %
+      [code, passed + failed + erred, passed, failed, erred]
+  end
+end

data/spec/dots_spec.rb

@@ -0,0 +1,131 @@
+require "spec/mocks"
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + "/../lib")
+require "dots"
+include Enumerable # To bring 1.8.7's Enumerator top-level.
+
+def enumerator?
+  RUBY_VERSION >= "1.8.7"
+end
+
+describe Dots do
+  it 'should be configurable for "."' do
+    Dots["."].should == "."
+    proc { Dots["."] = ":)" }.should_not raise_error
+    Dots["."].should == ":)"
+  end
+
+  it 'should be configurable for "F"' do
+    Dots["F"].should == "F"
+    proc { Dots["F"] = ":|" }.should_not raise_error
+    Dots["F"].should == ":|"
+  end
+
+  it 'should be configurable for "E"' do
+    Dots["E"].should == "E"
+    proc { Dots["E"] = ":(" }.should_not raise_error
+    Dots["E"].should == ":("
+  end
+
+  it 'should not be configurable for anything else' do
+    proc { Dots["A"] }.should raise_error(Dots::InvalidDot)
+    proc { Dots["A"] = ":D" }.should raise_error(Dots::InvalidDot)
+  end
+end
+
+describe "Monkey-patched" do
+  describe "Enumerable.instance_methods" do
+    it do
+      Enumerable.instance_methods.should include("each_with_dots")
+    end
+  end
+
+  describe "Enumerator.instance_methods" do
+    it do
+      Enumerator.instance_methods.should include("with_dots")
+    end
+  end if enumerator?
+
+  describe "Kernel.methods" do
+    it do
+      Kernel.private_instance_methods.should include("dots")
+    end
+  end
+end
+
+describe "each_with_dots" do
+  before :each do
+    @enumerated = 1..5
+    @io = StringIO.new
+    @proc = Proc.new {}
+  end
+
+  after :each do
+    @enumerated.each_with_dots @io, &@proc
+  end
+
+  it "should synchronize standard output" do
+    @io.should_receive(:sync=).twice
+  end
+
+  it 'should receive print dots' do
+    Dots.should_receive(:[]).exactly(5).times.with "."
+  end
+
+  it 'should receive print Fs' do
+    @proc = Proc.new { |n| raise }
+    Dots.should_receive(:[]).exactly(5).times.with "F"
+  end
+
+  it 'should receive print Es' do
+    @proc = Proc.new { |n| n / 0 }
+    Dots.should_receive(:[]).exactly(5).times.with "E"
+  end
+
+  it "should track the time" do
+    Time.should_receive :now
+  end
+
+  it 'should receive "report"' do
+    Dots.should_receive :report
+  end
+end
+
+describe "each.with_dots" do
+  before :each do
+    @it = (1..5).each
+  end
+
+  it do
+    @it.with_dots.should be_an(Enumerator)
+  end
+
+  it 'should receive "enum_for" with "each_with_dots"' do
+    @io = StringIO.new
+    @it.should_receive(:enum_for).with(:each_with_dots, @io).and_return @it
+    @it.with_dots(@io) {}.should == (1..5)
+  end
+end if enumerator?
+
+describe "with_dots" do
+  it "should print dots" do
+    Dots.should_receive(:[]).with "."
+    dots(1, StringIO.new) {}
+  end
+
+  it "should require a block" do
+    proc { dots }.should raise_error(LocalJumpError)
+  end
+
+  it "should synchronize standard output" do
+    io = StringIO.new
+    io.should_receive(:sync=).twice
+    dots(1, io) {}
+  end
+
+  it "should spin up and kill a thread" do
+    thread = mock "thread"
+    Thread.should_receive(:new).and_return thread
+    thread.should_receive :kill
+    dots(1, StringIO.new) {}
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: stephencelis-dots
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Stephen Celis
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-10 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Free progress dots for your scripts.
+email: 
+- stephen@stephencelis.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.rdoc
+- Manifest.txt
+- README.rdoc
+files: 
+- History.rdoc
+- Manifest.txt
+- Rakefile
+- README.rdoc
+- cucumber.yml
+- dots.gemspec
+- features
+- features/dots.feature
+- features/step_definitions/dots_steps.rb
+- features/support/env.rb
+- lib
+- lib/dots/kaoemoji.rb
+- lib/dots/rainbows.rb
+- lib/dots/redgreen.rb
+- lib/dots.rb
+- spec/dots_spec.rb
+has_rdoc: true
+homepage: http://github.com/stephencelis/dots
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: dots
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 3
+summary: Free progress dots for your scripts
+test_files: []
+