command_line_reporter 2.0 → 2.1

data/README.md

@@ -1,15 +1,23 @@
 ## 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.
+This gem provides a DSL that makes it easy to write reports of various types in ruby.  It eliminate
+the need to litter your source with *puts* statements instead providing a more readable, expressive
+interface to your application.  Some of the best features include:
 
-With the release of Version 2.0, it is now possible to produce tables with and without borders.  See
-the section on *Tables* for more examples.
+* Formatters that automatically indicate progress
+* Table syntax similar to HTML that makes it trivial to format your data in rows and columns
+* Easily created headers and footers for your report
+* Output suppression that makes it easy for your script to support a _quiet_ flag
 
 ### Installation
 
-It is up on rubygems.org so add it to your bundle or do it the old fashioned way:
+It is up on rubygems.org so add it to your bundle
+
+```bash
+gem 'command_line_reporter', '>=2.1'
+```
+
+or do it the old fashioned way:
 
 ```bash
 gem install command_line_reporter
@@ -20,10 +28,20 @@ gem install command_line_reporter
 The gem provides a mixin that can be included in your scripts.
 
 ```ruby
-include CommandLineReporter
+require 'command_line_reporter'
+
+class MyReport
+  include CommandLineReporter
+  ...
+end
 ```
 
-##### Standard Methods
+### [Wiki](https://github.com/wbailey/command_line_reporter/wiki)
+
+The [Wiki](https://github.com/wbailey/command_line_reporter/wiki) has all of the documentation
+necessary for getting you started.
+
+### API Reference
 
 There are several methods the mixin provides that do not depend on the formatter used:
 
@@ -74,277 +92,27 @@ There are several methods the mixin provides that do not depend on the formatter
     * :padding - The number of spaces to put on both the left and right of the text.
     * :align - Allowed values are left|right|center
 
-### Progress Formatter
-
-#### Example
-
-```ruby
-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
-      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_".
-
-```ruby
-formatter.message_string('working')
-```
-
-* _complete_string(string)_ - This defines the string that completes the message to the user for the
-  report.  The default value is "_complete_".
-
-```ruby
-formatter.complete_string('done')
-```
-
-* _indent_size(int)_ - The number of spaces to indent for a single indentation level.  The default
-  value is 2 spaces.
-
-```ruby
-formatter.indent_size(4)
-```
-
-#### 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
-
-```ruby
-report(:message => 'running', :complete => 'finished', :type => 'inline', :indent_size => 8) do
-  # code here
-end
-```
-
-### Tables
-
-Examples are always helpful so let's look at the following:
-
-```ruby
-require 'command_line_reporter'
-
-class Example
-  include CommandLineReporter
-
-  def run
-    table(:border => true) do
-     row do
-       column('NAME', :width => 20)
-       column('ADDRESS', :width => 30, :align => 'right', :padding => 5)
-       column('CITY', :width => 15)
-     end
-     row do
-       column('Ceaser')
-       column('1 Appian Way')
-       column('Rome')
-     end
-     row do
-       column('Richard Feynman')
-       column('1 Golden Gate')
-       column('Quantum Field')
-     end
-   end
-  end
-end
-
-Example.new.run
-```
-
-This produces the very simple output with 2 rows and 3 columns of data:
-
-```bash
-+----------------------+--------------------------------+-----------------+
-| NAME                 |                   ADDRESS      | CITY            | 
-+----------------------+--------------------------------+-----------------+
-| Ceaser               |              1 Appian Way      | Rome            | 
-+----------------------+--------------------------------+-----------------+
-| Richard Feynman      |             1 Golden Gate      | Quantum Field   | 
-+----------------------+--------------------------------+-----------------+
-```
-
-Notice how the properties of the columns for the second and third rows have been inherited from the
-first like in HTML.  This makes it a lot easier to write in freeform.  What if you have data to
-iterate over and have text that is wider than the column width you have selected?  Not a problem as
-the following example demonstrates all of the combinations of the various options:
-
-```ruby
-require 'command_line_reporter'
-
-class Example
-  include CommandLineReporter
+### To Do
 
-  def run
-    table(:border => true) do
-      3.times do
-        row do
-          i = 0
-          3.times do
-            i += 10
-            column('x' * (0 + rand(50)), :align => %w[left right center][rand(3)], :width => i, :padding => rand(5))
-          end
-        end
-      end
-    end
-  end
-end
-```
+* Add the ability for a column to span across others
+* Add the progress method to the top level mixin so that there is no need to invoke through the
+  formatter.
 
-This randomly produces a table with a border that has 3 rows and 3 columns.  Each column gets wider
-by 10 characters.  The alignment of the column is demonstrated and you can see where some data
-elements have padding around them.
+### License
 
-```bash
-+------------+----------------------+--------------------------------+
-| xxxxxxxxxx |    xxxxxxxxxxxxxx    |   xxxxxxxxxxxxxxxxxxxxxxxxxx   | 
-|     xxxxxx |       xxxxxxxxx      |   xxxxxx                       | 
-+------------+----------------------+--------------------------------+
-| xxxxxxxxxx |    xxxxxxxxxxxxxx    |   xxxxxxxxxxxxxxxxxxxxxxxxxx   | 
-| xxxxxxxxxx |    xxxxxxxxxxxxxx    |        xxxxxxxxxxxxxxxxx       | 
-| xxxxxxxxxx |    xxxxxxxxxxxxxx    |                                | 
-| xxxxxxx    |    xxxx              |                                | 
-+------------+----------------------+--------------------------------+
-| xxxxxxxxxx |         xxxx         |            xxxxxxxxxxxxxxxxxxx | 
-| xxxxxx     |                      |                                | 
-+------------+----------------------+--------------------------------+
-```
-
-This is all generated randomly to illustrate the features but you get the idea of how to use
-alignment, width and padding.
+Copyright (c) 2011-2012 Wes Bailey
 
-The best feature is *wrapping*.  If the text you are display in a cell is larger than the width it
-was given, it will automatically wrap it for you.  Padding and alignment are preserved.  It palso
-properly handles the case where the data in one cell causes the wrapping but other cells my not have
-the same number of lines to wrap.
+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:
 
-### To Do
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
 
-* Add the ability for a column to span across others
-* Add the progress method to the top level mixin so that there is no need to invoke through the
-  formatter.
+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/examples/quiet.rb

@@ -0,0 +1,40 @@
+require 'command_line_reporter'
+require 'ostruct'
+require 'optparse'
+
+class Example
+  include CommandLineReporter
+
+  def initialize
+    self.formatter = 'progress'
+  end
+
+  def run(options = {})
+    x = 0
+
+    suppress_output if options.quiet
+
+    report do
+      10.times do
+        x += 1
+        sleep 0.1
+        formatter.progress
+      end
+    end
+
+    restore_output if options.quiet
+  end
+end
+
+
+options = OpenStruct.new({:quiet => false})
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: ruby -I lib example/quiet.rb [-q|--quiet]"
+
+  opts.on('-q', '--quiet', 'do not print any output') do
+    options.quiet = true
+  end
+end.parse!
+
+Example.new.run(options)

data/examples/simple.rb

@@ -1,21 +1,21 @@
 require 'command_line_reporter'
 
+include CommandLineReporter
+
 class Example
-  include CommandLineReporter
+  def initialize
+    self.formatter = 'progress'
+  end
 
   def run
-    x,y,z = 0,0,0
-
-    header(:title => 'Simple Report Example', :align => 'center', :timestamp => true, :rule => true)
-
-    report(:message => 'calculating sums') do
-      x = 2 + 2
-      y = 10 - x
-      z = x + y
+    report do
+      sum = 0
+      10.times do
+        sum += 10
+        self.formatter.progress
+      end
+      aligned("Sum: #{sum}")
     end
-
-    footer(:title => 'Values', :width => 15)
-    %w(x y z).each {|v| aligned("#{v}: #{eval v}")}
   end
 end
 

data/examples/table.rb

@@ -24,7 +24,7 @@ class Example
       vertical_spacing(2)
     end
 
-    header(:title => 'A simple example of how column properties are inhereted from the first row')
+    header(:title => 'A simple example of how column properties are inherited from the first row')
 
     table(:border => true) do
       row do

data/lib/column.rb

@@ -19,8 +19,6 @@ class Column
     raise ArgumentError unless self.padding.to_s.match(/^\d+$/)
 
     self.size = self.width - 2 * self.padding
-
-    # self.freeze
   end
 
   def screen_rows

data/lib/command_line_reporter.rb

@@ -1,3 +1,4 @@
+require 'stringio'
 require 'table'
 
 Dir[File.join(File.dirname(__FILE__), '*_formatter.rb')].each {|r| require r}
@@ -12,6 +13,14 @@ module CommandLineReporter
     :align => 'left',
   }
 
+  def suppress_output
+    $stdout = StringIO.new
+  end
+
+  def restore_output
+    $stdout = STDOUT
+  end
+
   def formatter=(type = 'nested')
     name = type.capitalize + 'Formatter'
     klass = %W{CommandLineReporter #{name}}.inject(Kernel) {|s,c| s.const_get(c)}
@@ -85,7 +94,7 @@ module CommandLineReporter
   def table(options = {})
     @table = Table.new(options)
     yield
-    @table.to_s
+    @table.output
   end
 
   def row(options = {})

data/lib/row.rb

@@ -17,7 +17,7 @@ class Row
     @sep ||= '+' + self.columns.map {|c| '-' * (c.width + 2)}.join('+') + '+'
   end
 
-  def to_s
+  def output
     screen_count.times do |sr|
       line = (self.border) ? '| ' : ''
       self.columns.size.times do |mc|

data/lib/table.rb

@@ -32,12 +32,12 @@ class Table
     self.rows << row
   end
 
-  def to_s
+  def output
     return if self.rows.size == 0 # we got here with nothing to print to the screen
 
     puts self.rows[0].separator if self.border
     self.rows.each do |row|
-      row.to_s
+      row.output
       puts self.rows[0].separator if self.border
     end
   end

data/lib/version.rb

@@ -1,3 +1,3 @@
 module CommandLineReporter
-  VERSION = '2.0'
+  VERSION = '2.1'
 end

data/spec/column_spec.rb

@@ -46,22 +46,6 @@ describe Column do
         Column.new('test', :padding => 'asdf')
       }.to raise_error ArgumentError
     end
-
-    # it 'is immutable' do
-    #   c = Column.new('test')
-
-    #   expect {
-    #     c.text = 'asdf'
-    #   }.to raise_error RuntimeError, /frozen object/
-
-    #   expect {
-    #     c.width = 123
-    #   }.to raise_error RuntimeError, /frozen object/
-
-    #   expect {
-    #     c.padding = 123
-    #   }.to raise_error RuntimeError, /frozen object/
-    # end
   end
 
   describe '#screen_rows' do

data/spec/row_spec.rb

@@ -18,7 +18,7 @@ describe Row do
     end
   end
 
-  describe '#to_s' do
+  describe '#output' do
     before :each do
       @cols = [
         Column.new('asdf'),
@@ -41,46 +41,46 @@ describe Row do
 
     context 'no border' do
       context 'no wrap' do
-        it 'prints a single column' do
+        it 'outputs a single column' do
           subject.add(@cols[0])
           subject.should_receive(:puts).with(/^asdf#{@six_pieces}/)
-          subject.to_s
+          subject.output
         end
-        it 'prints three columns' do
+        it 'outputs three columns' do
           subject.add(@cols[0])
           subject.add(@cols[1])
           subject.add(@cols[2])
           subject.should_receive(:puts).with(/^asdf#{@six_spaces}#{@one_space}#{@three_spaces}qwer#{@three_spaces}#{@one_space}#{@six_spaces}zxcv $/)
-          subject.to_s
+          subject.output
         end
       end
 
       context 'with wrapping' do
-        it 'prints a single column' do
+        it 'outputs a single column' do
           subject.add(@cols[3])
           subject.should_receive(:puts).with(/^#{@ten_xs}#{@one_space}$/)
           subject.should_receive(:puts).with(/^#{@ten_xs}#{@one_space}$/)
           subject.should_receive(:puts).with(/^#{@five_xs}#{@six_spaces}$/)
-          subject.to_s
+          subject.output
         end
 
-        it 'prints multiple columns of the same size' do
+        it 'outputs multiple columns of the same size' do
           subject.add(@cols[3])
           subject.add(@cols[4])
           subject.should_receive(:puts).with(/^#{@ten_xs}#{@one_space}#{@ten_xs}#{@one_space}$/)
           subject.should_receive(:puts).with(/^#{@ten_xs}#{@one_space}#{@ten_xs}#{@one_space}$/)
           subject.should_receive(:puts).with(/^#{@five_xs}#{@nine_spaces}#{@five_xs}#{@three_spaces}$/)
-          subject.to_s
+          subject.output
         end
 
-        it 'prints multiple columns with different size' do
+        it 'outputs multiple columns with different sizes' do
           subject.add(@cols[5])
           subject.add(@cols[3])
           subject.should_receive(:puts).with(/^#{@ten_xs}#{@one_space}#{@ten_xs}#{@one_space}$/)
           subject.should_receive(:puts).with(/^#{@ten_xs}#{@one_space}#{@ten_xs}#{@one_space}$/)
           subject.should_receive(:puts).with(/^#{@ten_xs}#{@one_space}#{@five_xs}#{@six_spaces}$/)
           subject.should_receive(:puts).with(/^#{@five_xs} {5,17}$/)
-          subject.to_s
+          subject.output
         end
       end
     end

data/spec/table_spec.rb

@@ -38,7 +38,7 @@ describe Table do
       row.add(cols[1])
       t.add(row)
       output = capture_stdout {
-        t.to_s
+        t.output
       }
     end
   end

metadata

@@ -1,37 +1,41 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: command_line_reporter
-version: !ruby/object:Gem::Version
-  version: '2.0'
+version: !ruby/object:Gem::Version 
   prerelease: 
+  version: "2.1"
 platform: ruby
-authors:
+authors: 
 - Wes
 - Bailey
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-11 00:00:00.000000000Z
-dependencies:
-- !ruby/object:Gem::Dependency
+
+date: 2012-01-29 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
   name: bundler
-  requirement: &2152892720 !ruby/object:Gem::Requirement
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *2152892720
-description: This gem makes it easy to provide a report while your ruby script is
-  executing
+  version_requirements: *id001
+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:
+
+files: 
 - examples/nested.rb
 - examples/progress.rb
+- examples/quiet.rb
 - examples/simple.rb
 - examples/table.rb
 - lib/column.rb
@@ -55,32 +59,35 @@ files:
 - spec/table_spec.rb
 homepage: http://github.com/wbailey/command_line_reporter
 licenses: []
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-      segments:
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -154884230452992637
+      segments: 
       - 0
-      hash: 3958532185567160349
-required_rubygems_version: !ruby/object:Gem::Requirement
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
 requirements: []
+
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
 summary: A tool for providing interactive command line applications
-test_files:
+test_files: 
 - spec/column_spec.rb
 - spec/command_line_reporter_spec.rb
 - spec/nested_formatter_spec.rb