command_line_reporter 1.0.0

data/README.md

@@ -0,0 +1,196 @@
+## Command Line Reporter
+
+This gem provides an simple way to add RSpec like formatting of the output of your ruby scripts.  It
+eliminates the need to litter your code with *puts* statements instead providing a cleaner, more
+ruby like way of reporting progress to the user throught the command line interface.
+
+### Installation
+
+It is up on rubygems.org so add it to your bundle or do it the old fashioned way:
+
+```bash
+gem install command_line_reporter
+```
+
+### Usage
+
+The gem provides a mixin that can be included in your scripts.
+
+```ruby
+include CommandLineReporter
+```
+
+#### Standard Methods
+
+There are several methods the mixin provides that do not depend on the formatter used:
+
+1. _report(hash) {block}_
+  * The first argument is a hash that defines the options for the method. See the details in the
+    formatter section for allowed values.
+  * The second argument is a block of ruby code that you want executed within the context of the
+    reporter.  Any ruby code is allowed.  See the examples that follow in the formatter sections for
+    details.
+1. _formatter=(string)_
+  * Simple string indicating the formatter you want your application to use.  At present the 2
+    formatters are:
+
+    2. Progress - indicated by the string '_progress_'
+    2. Nested - indicated by the string '_nested_'
+
+    The default is _nested_.
+
+### Progress Formatter
+
+#### Example
+
+```ruby
+require 'command_line_reporter'
+
+class Example
+  include CommandLineReporter
+
+  def initialize
+    formatter = 'progress'
+  end
+
+  def run
+    x = 0
+    report do
+      10.times do
+        x += 1
+        formatter.progress
+      end
+    end
+  end
+end
+
+Example.new.run
+```
+
+This simply produces 10 dots (.) in succession:
+
+```bash
+[~/scratch]$ ruby example.rb
+..........
+```
+
+#### Indicator
+
+The indicator is the string that is displayed in the command line interface that indicates progress.
+The default is the dot (.) but any string is allowed.  In fact one can use the erase character to
+get crafty with displaying percent complete in place.
+
+#### Instance Methods
+
+* _indicator(string)_ - This overrides the default value of the dot (.) being used for all calls to
+   the report method.
+
+```ruby
+formatter.indicator('*')
+```
+
+* _progress(string)_ - Call this method to invoke the output to the command line interface.  The
+   string overrides the indicator for this call only.
+
+```ruby
+formatter.progress
+formatter.progress("^H^H^H10%")
+```
+
+### Nested Formatter
+
+The nested formatter concept is inspired by the documentation formatter in RSpec.  The idea is to be
+able to create nested grouping levels of output that are very readable as the code is being
+executed.
+
+#### Example
+
+```ruby
+require 'command_line_reporter'
+
+class Example
+  include CommandLineReporter
+
+  def initialize
+    self.formatter = 'nested'
+  end
+
+  def run
+    x,y,z = 0,0,0
+
+    report(:message => 'calculating first expression') do
+      x = 2 + 2
+      2.times do
+        report(:message => 'calculating second expression') do
+          y = 10 - x
+          10.times do |i|
+            report(:message => 'pixelizing', :type => 'inline', :complete => "#{i*10+10}%") do
+              z = x + y
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Example.new.run
+
+```
+
+This produces the more complex output:
+
+```
+[~/scratch]$ ruby example.rb
+calculating first expression
+  calculating second expression
+    pixelizing...10%
+    pixelizing...20%
+    pixelizing...30%
+    pixelizing...40%
+    pixelizing...50%
+    pixelizing...60%
+    pixelizing...70%
+    pixelizing...80%
+    pixelizing...90%
+    pixelizing...100%
+  complete
+  calculating second expression
+    pixelizing...10%
+    pixelizing...20%
+    pixelizing...30%
+    pixelizing...40%
+    pixelizing...50%
+    pixelizing...60%
+    pixelizing...70%
+    pixelizing...80%
+    pixelizing...90%
+    pixelizing...100%
+  complete
+complete
+```
+
+#### Instance Methods
+
+* _message_string(string)_ - This defines the string that is displayed as the first part of the
+  message to the user. The default value is "_working_". 
+* _complete_string(string)_ - This defines the string that completes the message to the user for the
+  report.  The default value is "_complete_".
+* _indent_size(int)_ - The number of spaces to indent for a single indentation level.  The default
+  value is 2 spaces.
+
+#### Report Options
+
+The following are the allowed values of the options hash argument to the _report_ method:
+
+* _message_ - The string that is displayed as the first part of the message to the user
+* _complete_ - The string that completes the message to the user
+* _type_ - Define as 'inline' if you want the message and complete strings on the same line
+* _indent_size_ - The number of spaces to indent the current level
+
+### To Do
+
+1. Add the progress method to the top level mixin so that there is no need to invoke through the
+   formatter.
+2. Add a _preface_ and _epilogue_ methods so that beginning and ending aspects of the report may be
+   added without using _puts_ and _print_.

data/examples/nested.rb

@@ -0,0 +1,38 @@
+require 'command_line_reporter'
+
+class Example
+  include CommandLineReporter
+
+  def initialize
+    self.formatter = 'nested'
+    self.formatter.complete_string = 'done'
+  end
+
+  def run
+    x,y,z = 0,0,0
+
+    report(:message => 'calculating first expression') do
+      x = 2 + 2
+      sleep 1
+
+      2.times do
+        report(:message => 'calculating second expression') do
+          y = 10 - x
+          sleep 1
+
+          10.times do |i|
+            report(:message => 'pixelizing', :type => 'inline', :complete => "#{i*10+10}%") do
+              z = x + y
+              sleep 1
+            end
+          end
+        end
+      end
+    end
+
+    puts '-' * 20
+    %w(x y z).each {|v| puts "#{v}: #{eval v}"}
+  end
+end
+
+Example.new.run

data/examples/progress.rb

@@ -0,0 +1,51 @@
+require 'command_line_reporter'
+
+class Example
+  include CommandLineReporter
+
+  def initialize
+    self.formatter = 'progress'
+  end
+
+  def run
+    x = 0
+
+    report do
+      10.times do
+        x += 1
+        formatter.progress
+
+        10.times do
+          x += 1
+          formatter.progress
+        end
+      end
+    end
+
+    y = 0
+
+    report do
+      10.times do
+        y += 1
+        sleep 1
+        formatter.progress("#{y*10+10}%")
+      end
+    end
+
+    report do
+      3.times do
+        formatter.progress("\\")
+        sleep 1
+        formatter.progress("/")
+        sleep 1
+        formatter.progress("-")
+        sleep 1
+      end
+    end
+
+    puts "x: #{x}"
+    puts "y: #{y}"
+  end
+end
+
+Example.new.run

data/lib/command_line_reporter.rb

@@ -0,0 +1,20 @@
+Dir[File.join(File.dirname(__FILE__), '*_formatter.rb')].each {|r| require r}
+
+module CommandLineReporter
+  attr_reader :formatter
+
+  def report(options = {}, &block)
+    self.formatter = 'nested' if self.formatter.nil?
+    self.formatter.format(options, block)
+  end
+
+  def formatter=(type = 'nested')
+    name = type.capitalize + 'Formatter'
+    klass = %W{CommandLineReporter #{name}}.inject(Kernel) {|s,c| s.const_get(c)}
+
+    # Each formatter is a singleton that responds to #instance
+    @formatter = klass.instance
+  rescue
+    raise ArgumentError, 'Invalid formatter specified'
+  end
+end

data/lib/nested_formatter.rb

@@ -0,0 +1,56 @@
+require 'singleton'
+
+module CommandLineReporter
+  class NestedFormatter
+    include Singleton
+
+    attr_accessor :indent_size, :complete_string, :message_string
+
+    def format(options, block)
+      raise ArgumentError unless (options.keys - [:message, :type, :complete, :indent_size]).empty?
+
+      indent_level :incr
+
+      padding = ' ' * @indent_level * (options[:indent_size] || self.indent_size)
+
+      message_str = padding + (options[:message] || self.message_string)
+      complete_str = options[:complete] || self.complete_string
+
+      if options[:type] == 'inline'
+        print "#{message_str}..."
+      else
+        puts message_str
+        complete_str = padding + complete_str
+      end
+
+      block.call
+
+      puts complete_str
+
+      indent_level :decr
+    end
+
+    def message_string
+      @message_string ||= 'working'
+    end
+
+    def complete_string
+      @complete_string ||= 'complete'
+    end
+
+    def indent_size
+      @indent_size ||= 2
+    end
+
+    private
+
+    def indent_level(value)
+      case value
+      when :incr
+        @indent_level = (@indent_level) ? @indent_level + 1 : 0
+      when :decr
+        @indent_level -= 1
+      end
+    end
+  end
+end

data/lib/progress_formatter.rb

@@ -0,0 +1,23 @@
+require 'singleton'
+
+module CommandLineReporter
+  class ProgressFormatter
+    include Singleton
+
+    attr_accessor :indicator
+
+    def format(options, block)
+      self.indicator = options[:indicator] if options[:indicator]
+      block.call
+      puts
+    end
+
+    def progress(override = nil)
+      print override || self.indicator
+    end
+
+    def indicator
+      @indicator ||= '.'
+    end
+  end
+end

data/lib/version.rb

@@ -0,0 +1,3 @@
+module CommandLineReporter
+  VERSION = '1.0.0'
+end

data/spec/command_line_reporter_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+require 'command_line_reporter'
+
+describe CommandLineReporter do
+  let :use_class do
+    Class.new do
+      include CommandLineReporter
+    end
+  end
+
+  subject { use_class.new }
+
+  describe '#formatter=' do
+    it 'only allows allowed formatters' do
+      lambda {
+        subject.formatter = 'asfd'
+      }.should raise_exception ArgumentError
+    end
+
+    it 'specifies the progress formatter' do
+      subject.formatter = 'progress'
+      subject.formatter.class.should == CommandLineReporter::ProgressFormatter
+    end
+
+    it 'specifies the nested formatter' do
+      subject.formatter = 'nested'
+      subject.formatter.class.should == CommandLineReporter::NestedFormatter
+    end
+  end
+
+  describe '#report' do
+    it 'uses the nested formatter as default' do
+      subject.report { }
+      subject.formatter.class.should == CommandLineReporter::NestedFormatter
+    end
+  end
+end

data/spec/nested_formatter_spec.rb

@@ -0,0 +1,250 @@
+require 'spec_helper'
+require 'nested_formatter'
+
+describe CommandLineReporter::NestedFormatter do
+  subject { CommandLineReporter::NestedFormatter.instance }
+
+  describe '#method default values' do
+    its(:message_string) { should == 'working' }
+    its(:complete_string) { should == 'complete' }
+    its(:indent_size) { should eq 2 }
+  end
+
+  describe '#format' do
+    context 'argument validation' do
+      before :all do
+        @indent_size = subject.indent_size
+      end
+
+      # Restore the singleton to its original state to ensure clean tests
+      after :each do
+        subject.indent_size = @indent_size
+      end
+
+      it 'raises exception when there is an invalid argument' do
+        lambda {
+          subject.format({:asdf => true}, lambda { })
+        }.should raise_exception ArgumentError
+      end
+
+      it 'raises an exception when a block is not given' do
+        lambda {
+          subject.format({:message => 'test'})
+        }.should raise_exception
+      end
+
+      it 'accepts valid arguments' do
+        subject.should_receive(:puts).with('test')
+        subject.should_receive(:puts).with('complete')
+
+        lambda {
+          subject.format({:message => 'test'}, lambda { }) do
+          end
+        }.should_not raise_exception
+      end
+    end
+
+    context 'not nested' do
+      before :all do
+        @complete_string = subject.complete_string
+        @indent_size = subject.indent_size
+      end
+
+      # Restore the singleton to its original state to ensure clean tests
+      after :each do
+        subject.complete_string = @complete_string
+        subject.indent_size = @indent_size
+      end
+
+      it 'performs a wrapped report' do
+        subject.should_receive(:puts).with('working')
+        subject.should_receive(:puts).with('complete')
+
+        subject.format({ }, lambda { })
+      end
+
+      it 'performs a wrapped report overriding the message' do
+        subject.should_receive(:puts).with('test')
+        subject.should_receive(:puts).with('complete')
+
+        subject.format({:message => 'test'}, lambda { })
+      end
+
+      it 'performs an inline report' do
+        subject.should_receive(:print).with('test...')
+        subject.should_receive(:puts).with('complete')
+        subject.should_receive(:print).with('test2...')
+        subject.should_receive(:puts).with('complete')
+
+        subject.format({:message => 'test', :type => 'inline'}, lambda { })
+        subject.format({:message => 'test2', :type => 'inline'}, lambda { })
+      end
+
+      it 'overrides the default for all invocations of a wrapped report' do
+        subject.complete_string = 'done'
+        subject.should_receive(:puts).with('test')
+        subject.should_receive(:puts).with('done')
+        subject.should_receive(:puts).with('test2')
+        subject.should_receive(:puts).with('done')
+
+        subject.format({:message => 'test'}, lambda { })
+        subject.format({:message => 'test2'}, lambda { })
+      end
+
+      it 'overrides the default complete string for a wrapped report' do
+        subject.should_receive(:puts).with('test')
+        subject.should_receive(:puts).with('done')
+        subject.should_receive(:puts).with('test2')
+        subject.should_receive(:puts).with('finally')
+
+        subject.format({:message => 'test', :complete => 'done'}, lambda { })
+        subject.format({:message => 'test2', :complete => 'finally'}, lambda { })
+      end
+
+      it 'overrides the default complete string for an inline report' do
+        subject.should_receive(:print).with('test...')
+        subject.should_receive(:puts).with('done')
+        subject.should_receive(:print).with('test2...')
+        subject.should_receive(:puts).with('finally')
+
+        subject.format({:message => 'test', :type => 'inline', :complete => 'done'}, lambda { })
+        subject.format({:message => 'test2', :type => 'inline', :complete => 'finally'}, lambda { })
+      end
+
+      it 'performs another wrapped report to ensure defaul behavior' do
+        subject.should_receive(:puts).with('test')
+        subject.should_receive(:puts).with('complete')
+        subject.should_receive(:puts).with('test2')
+        subject.should_receive(:puts).with('complete')
+
+        subject.format({:message => 'test'}, lambda { })
+        subject.format({:message => 'test2'}, lambda { })
+      end
+    end
+
+    context 'nested commands' do
+      before :all do
+        @indent_size = subject.indent_size
+      end
+
+      # Restore the singleton to its original state to ensure clean tests
+      after :each do
+        subject.indent_size = @indent_size
+      end
+
+      it 'indents the nested wrapped messages' do
+        subject.should_receive(:puts).with('test')
+        subject.should_receive(:puts).with('  test2')
+        subject.should_receive(:puts).with('  complete')
+        subject.should_receive(:puts).with('complete')
+
+        nested = lambda {
+        }
+
+        subject.format({:message => 'test'}, lambda {
+          subject.format({:message => 'test2'}, lambda {})
+        })
+      end
+
+      it 'indents the multiple nested wrapped messages' do
+        subject.should_receive(:puts).with('test')
+        subject.should_receive(:puts).with('  test2')
+        subject.should_receive(:puts).with('    test3')
+        subject.should_receive(:puts).with('    complete')
+        subject.should_receive(:puts).with('  complete')
+        subject.should_receive(:puts).with('complete')
+
+        subject.format({:message => 'test'}, lambda {
+          subject.format({:message => 'test2'}, lambda {
+            subject.format({:message => 'test3'}, lambda { })
+          })
+        })
+      end
+
+      it 'indents the nested wrapped and inline messages' do
+        subject.should_receive(:puts).with('test')
+        subject.should_receive(:print).with('  test2...')
+        subject.should_receive(:puts).with('complete')
+        subject.should_receive(:puts).with('complete')
+
+        subject.format({:message => 'test'}, lambda {
+          subject.format({:message => 'test2', :type => 'inline'}, lambda { })
+        })
+      end
+
+      it 'indents the multiple nested wrapped messages' do
+        subject.should_receive(:puts).with('test')
+        subject.should_receive(:puts).with('  test2')
+        subject.should_receive(:print).with('    test3...')
+        subject.should_receive(:puts).with('complete')
+        subject.should_receive(:puts).with('  complete')
+        subject.should_receive(:puts).with('complete')
+
+        subject.format({:message => 'test'}, lambda {
+          subject.format({:message => 'test2'}, lambda {
+            subject.format({:message => 'test3', :type => 'inline'}, lambda { })
+          })
+        })
+      end
+
+      it 'overrides the indent spacing of all messages' do
+        subject.should_receive(:puts).with('test')
+        subject.should_receive(:puts).with('    test2')
+        subject.should_receive(:print).with('        test3...')
+        subject.should_receive(:puts).with('complete')
+        subject.should_receive(:puts).with('    complete')
+        subject.should_receive(:puts).with('complete')
+
+        subject.indent_size = 4
+
+        subject.format({:message => 'test'}, lambda {
+          subject.format({:message => 'test2'}, lambda {
+            subject.format({:message => 'test3', :type => 'inline'}, lambda { })
+          })
+        })
+      end
+
+      it 'overrides the indent spacing of specific message' do
+        subject.should_receive(:puts).with('test')
+        subject.should_receive(:puts).with('      test2')
+        subject.should_receive(:print).with('      test3...')
+        subject.should_receive(:puts).with('complete')
+        subject.should_receive(:puts).with('      complete')
+        subject.should_receive(:puts).with('complete')
+
+        subject.indent_size = 4
+
+        subject.format({:message => 'test'}, lambda {
+          subject.format({:message => 'test2', :indent_size => 6}, lambda {
+            subject.format({:message => 'test3', :type => 'inline', :indent_size => 3}, lambda { })
+          }) 
+        })
+      end
+
+      it 'performs the sums specified in the block' do
+        x,y,z = 0,0,0
+
+        subject.should_receive(:puts).with('sum x and 10')
+        subject.should_receive(:puts).with('  y is the difference of 20 and x')
+        subject.should_receive(:puts).with('    z = x + y')
+        subject.should_receive(:puts).with('    complete')
+        subject.should_receive(:puts).with('  complete')
+        subject.should_receive(:puts).with('complete')
+
+        subject.format({:message => 'sum x and 10'}, lambda {
+          x = x + 10
+          subject.format({:message => 'y is the difference of 20 and x'}, lambda {
+            y = 20 - x
+            subject.format({:message => 'z = x + y'}, lambda {
+              z = x + y
+            })
+          })
+        })
+
+        x.should == 10
+        y.should == 10
+        z.should == 20
+      end
+    end
+  end
+end

data/spec/progress_formatter_spec.rb

@@ -0,0 +1,61 @@
+require 'spec_helper'
+require 'progress_formatter'
+
+describe CommandLineReporter::ProgressFormatter do
+  subject { CommandLineReporter::ProgressFormatter.instance }
+
+  describe '#method default values' do
+    its(:indicator) { should == '.' }
+  end
+
+  describe '#format' do
+    it 'displays dots for the indicator' do
+      subject.should_receive(:print).exactly(10).times.with('.')
+      subject.should_receive(:puts).exactly(1).times
+
+      subject.format({}, lambda {
+        10.times {subject.progress}
+      })
+    end
+
+    it 'uses the defined indicator' do
+      subject.indicator = '+'
+      subject.should_receive(:print).exactly(10).times.with('+')
+      subject.should_receive(:puts)
+
+      subject.format({}, lambda {
+        10.times {subject.progress}
+      })
+
+    end
+
+    it 'allows override of the indicator' do
+      subject.should_receive(:print).exactly(10).times.with('=')
+      subject.should_receive(:puts)
+
+      subject.format({:indicator => '='}, lambda {
+        10.times {subject.progress}
+      })
+    end
+  end
+
+  describe '#progress' do
+    it 'allows override of the indicator' do
+      subject.should_receive(:print).exactly(10).times.with('+')
+      subject.should_receive(:puts)
+
+      subject.format({}, lambda {
+        10.times {subject.progress('+')}
+      })
+    end
+
+    it 'allows any indicator' do
+      subject.should_receive(:print).exactly(10).times
+      subject.should_receive(:puts)
+
+      subject.format({}, lambda {
+        10.times {|i| subject.progress("#{i}")}
+      })
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+$: << File.join(File.dirname(__FILE__), '..', 'lib')

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: command_line_reporter
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Wes
+- Bailey
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-11-28 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: &2151943860 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *2151943860
+description: This gem makes it easy to provide a report while your ruby script is
+  executing
+email: baywes@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- examples/nested.rb
+- examples/progress.rb
+- lib/command_line_reporter.rb
+- lib/nested_formatter.rb
+- lib/progress_formatter.rb
+- lib/version.rb
+- README.md
+- spec/command_line_reporter_spec.rb
+- spec/nested_formatter_spec.rb
+- spec/progress_formatter_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/wbailey/command_line_reporter
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 4291773844303302858
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A tool for providing interactive command line applications
+test_files:
+- spec/command_line_reporter_spec.rb
+- spec/nested_formatter_spec.rb
+- spec/progress_formatter_spec.rb
+- spec/spec_helper.rb