command_line_reporter 2.1 → 3.0

data/README.md

@@ -1,6 +1,6 @@
 ## Command Line Reporter
 
-This gem provides a DSL that makes it easy to write reports of various types in ruby.  It eliminate
+This gem provides a DSL that makes it easy to write reports of various types in ruby.  It eliminates
 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:
 
@@ -9,12 +9,15 @@ interface to your application.  Some of the best features include:
 * Easily created headers and footers for your report
 * Output suppression that makes it easy for your script to support a _quiet_ flag
 
+The latest release also supports colors allowing you to distinguish data in new ways including bold
+if your terminal supports it.
+
 ### Installation
 
-It is up on rubygems.org so add it to your bundle
+It is up on rubygems.org so add it to your bundle in the Gemfile
 
 ```bash
-gem 'command_line_reporter', '>=2.1'
+gem 'command_line_reporter', '>=3.0'
 ```
 
 or do it the old fashioned way:
@@ -55,6 +58,8 @@ There are several methods the mixin provides that do not depend on the formatter
     Either true|false.  _Default: false_
   * _:rule_ - true|false indicates whether to include a horizontal rule below|above the
     header|footer.  _Default: false_
+  * _:color_ - The color to use for the terminal output i.e. 'red' or 'blue' or 'green'
+  * _:bold_ - true|false to boldface the font
 * _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.
@@ -69,34 +74,51 @@ There are several methods the mixin provides that do not depend on the formatter
 * _horizontal_rule(hash)_
   * _:char_ - The character used to build the rule.  _Default: '-'_
   * _:width_ - The width in characters of the rule.  _Default: 100_
+  * _:color_ - The color to use for the terminal output i.e. 'red' or 'blue' or 'green'
+  * _:bold_ - true|false to boldface the font
 * _vertical_spacing(int)_
   * Number of blank lines to output.  _Default: 1_
 * _datetime(hash)_
   * _:align_ - 'left'|'center'|'right' alignment of the timestamp.  _Default: 'left'_
   * _:width_ - The width of the string in characters.  _Default: 100_
   * _:format_ - Any allowed format from #strftime#.  _Default: %Y-%m-%d %H:%I:%S%p_
+  * _:color_ - The color to use for the terminal output i.e. 'red' or 'blue' or 'green'
+  * _:bold_ - true|false to boldface the font
 * _aligned(string, hash)_
   * _text_ - String to display
   * _:align_ - 'left'|'right'|'center' align the string text.  _Default: 'left'_
   * _:width_ - The width in characters of the string text.  _Default: 100_
+  * _:color_ - The color to use for the terminal output i.e. 'red' or 'blue' or 'green'
+  * _:bold_ - true|false to boldface the font
 * _table(hash) {block}_
   * The first argument is a hash that defines properties of the table.
     * _:border_ - true|false indicates whether to include borders around the table cells
   * The second argument is a block which includes calls the to the _row_ method
 * _row {block}_
-  * Only argument is a block with calls to _column_ allowed
+  * _:header_ - Set to true to indicate if this is a header row in the table.
+  * _:color_ - The color to use for the terminal output i.e. 'red' or 'blue' or 'green'
+  * _:bold_ - true|false to boldface the font
 * _column(string, hash)_
   * _text_ - String to display in the table cell
   * _options_ - The options to define the column
     * :width - defines the width of the column
     * :padding - The number of spaces to put on both the left and right of the text.
     * :align - Allowed values are left|right|center
+    * :color - The color to use for the terminal output i.e. 'red' or 'blue' or 'green'
+    * :bold - true|false to boldface the font
 
 ### To Do
 
-* 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.
+* Refactor the table structure to use a formatter that produces the current ascii output
+* After the formatter is added to a table then create one for html output
+* Add the ability for a column to span across others in a table
+
+### Contributors
+
+* Thanks to [Mike Gunderloy](https://github.com/ffmike) for suggesting the need for suppressing
+  output and putting together a fantastic pull request and discussion
+* Thanks to [Jason Rogers](https://github.com/jacaetevha) and [Peter
+  Suschlik](https://github.com/splattael) for their contributions as well on items I missed
 
 ### License
 

data/examples/nested.rb

@@ -30,8 +30,8 @@ class Example
       end
     end
 
-    puts '-' * 20
-    %w(x y z).each {|v| puts "#{v}: #{eval v}"}
+    horizontal_rule(:width => 20)
+    %w(x y z).each {|v| aligned "#{v}: #{eval v}"}
   end
 end
 

data/examples/progress.rb

@@ -16,12 +16,14 @@ class Example
       10.times do
         x += 1
         sleep 0.1
-        formatter.progress
+        # formatter.progress
+        progress
 
         10.times do
           x += 1
           sleep 0.1
-          formatter.progress
+          # formatter.progress
+          progress
         end
       end
     end
@@ -32,24 +34,24 @@ class Example
       10.times do
         y += 1
         sleep 0.1
-        formatter.progress("#{y*10}%")
+        progress("#{y*10}%")
       end
     end
 
     report do
       3.times do
-        formatter.progress("\\")
+        progress("\\")
         sleep 0.1
-        formatter.progress("/")
+        progress("/")
         sleep 0.1
-        formatter.progress("-")
+        progress("-")
         sleep 0.1
       end
     end
 
-    report do
+    report(:color => 'red') do
       100.times do
-        self.formatter.progress(erase_chars + NYAN_CHARS)
+        progress(erase_chars + NYAN_CHARS)
         sleep 0.1
       end
     end

data/examples/quiet.rb

@@ -18,7 +18,7 @@ class Example
       10.times do
         x += 1
         sleep 0.1
-        formatter.progress
+        progress
       end
     end
 

data/examples/simple.rb

@@ -12,8 +12,9 @@ class Example
       sum = 0
       10.times do
         sum += 10
-        self.formatter.progress
+        progress
       end
+      vertical_spacing
       aligned("Sum: #{sum}")
     end
   end

data/examples/table.rb

@@ -1,3 +1,4 @@
+# recoil  <co>mmand_<li>ne_<re>porter
 require 'command_line_reporter'
 
 class Example
@@ -7,40 +8,61 @@ class Example
     header(:title => 'TABLE EXAMPLES - Borders, Wrapping, Alignment and Padding', :align => 'center', :width => 70)
 
     2.times do |j|
-      header(:title => "Table #{j}", :align => 'center', :width => 65)
+      header :title => "Table #{j}", :align => 'center', :width => 65
 
-      table(:border => j % 2 == 0) do
+      table :border => j % 2 == 0  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))
+              column 'x' * (0 + rand(50)), :align => %w[left right center][rand(3)], :width => i, :padding => rand(5) 
             end
           end
         end
       end
 
-      vertical_spacing(2)
+      vertical_spacing 2
     end
 
-    header(:title => 'A simple example of how column properties are inherited from the first row')
+    header :title => 'An example of a table with a header row.  The color and border properties are not inherited'
 
-    table(:border => true) do
-      row do
-        column('NAME', :width => 20)
-        column('ADDRESS', :width => 30, :align => 'right', :padding => 5)
-        column('CITY', :width => 15)
+    table :border => true do
+      row :header => true, :color => 'red'  do
+        column 'MY NAME IS REALLY LONG AND WILL WRAP AND HOPE', :width => 20, :align => 'center', :color => 'blue'
+        column 'ADDRESS', :width => 30, :padding => 5
+        column 'CITY', :width => 15
+      end
+      row :color => 'green', :bold => true do
+        column 'Ceaser'
+        column '1 Appian Way'
+        column 'Rome'
       end
       row do
-        column('Ceaser')
-        column('1 Appian Way')
-        column('Rome')
+        column 'Richard Feynman'
+        column '1 Golden Gate'
+        column 'Quantum Field'
+      end
+    end
+
+    vertical_spacing 2
+    header :title => 'The same table with the properties inherited from the first row'
+
+    table :border => true do
+      row :color => 'red' do
+        column 'MY NAME IS REALLY LONG AND WILL WRAP AND HOPE', :width => 20, :align => 'center', :color => 'blue'
+        column 'ADDRESS', :width => 30, :padding => 5
+        column 'CITY', :width => 15
+      end
+      row :color => 'green', :bold => true do
+        column 'Ceaser'
+        column '1 Appian Way'
+        column 'Rome'
       end
       row do
-        column('Richard Feynman')
-        column('1 Golden Gate')
-        column('Quantum Field')
+        column 'Richard Feynman'
+        column '1 Golden Gate'
+        column 'Quantum Field'
       end
     end
   end

data/lib/column.rb

@@ -1,50 +1,67 @@
 require 'options_validator'
+require 'colored'
 
-class Column
-  include OptionsValidator
+module CommandLineReporter
+  class Column
+    include OptionsValidator
 
-  VALID_OPTIONS = [:width, :padding, :align]
-  attr_accessor :text, :size, *VALID_OPTIONS
+    VALID_OPTIONS = [:width, :padding, :align, :color, :bold, :underline, :reversed]
+    attr_accessor :text, :size, *VALID_OPTIONS
 
-  def initialize(text = nil, options = {})
-    self.validate_options(options, *VALID_OPTIONS)
+    def initialize(text = nil, options = {})
+      self.validate_options(options, *VALID_OPTIONS)
 
-    self.text = text
+      self.text = text
 
-    self.width = options[:width] || 10
-    self.align = options[:align] || 'left'
-    self.padding = options[:padding] || 0
+      self.width = options[:width] || 10
+      self.align = options[:align] || 'left'
+      self.padding = options[:padding] || 0
+      self.color = options[:color] || nil
+      self.bold = options[:bold] || false
+      self.underline = options[:underline] || false
+      self.reversed = options[:reversed] || false
 
-    raise ArgumentError unless self.width > 0
-    raise ArgumentError unless self.padding.to_s.match(/^\d+$/)
+      raise ArgumentError unless self.width > 0
+      raise ArgumentError unless self.padding.to_s.match(/^\d+$/)
 
-    self.size = self.width - 2 * self.padding
-  end
+      self.size = self.width - 2 * self.padding
+    end
 
-  def screen_rows
-    if self.text.nil? || self.text.empty?
-      [' ' * self.width]
-    else
-      self.text.scan(/.{1,#{self.size}}/m).map {|s| to_cell(s)}
+    def screen_rows
+      if self.text.nil? || self.text.empty?
+        [' ' * self.width]
+      else
+        self.text.scan(/.{1,#{self.size}}/m).map {|s| to_cell(s)}
+      end
     end
-  end
 
-  private
-
-  def to_cell(str)
-    cell =  if str.empty?
-              ' ' * self.size
-            else
-              case self.align
-              when 'left'
-                str.ljust(self.size)
-              when 'right'
-                str.rjust(self.size)
-              when 'center'
-                str.ljust((self.size - str.size)/2.0 + str.size).rjust(self.size)
+    private
+
+    def to_cell(str)
+      # NOTE: For making underline and reversed work Change so that based on the
+      # unformatted text it determines how much spacing to add left and right
+      # then colorize the cell text
+      cell =  if str.empty?
+                ' ' * self.size
+              else
+                case self.align
+                when 'left'
+                  str.ljust(self.size)
+                when 'right'
+                  str.rjust(self.size)
+                when 'center'
+                  str.ljust((self.size - str.size)/2.0 + str.size).rjust(self.size)
+                end
               end
-            end
 
-    ' ' * self.padding + cell + ' ' * self.padding
+      padding_str = ' ' * self.padding
+      padding_str + colorize(cell) + padding_str
+    end
+
+    def colorize(str)
+      str = str.send(color) if self.color
+      str = str.send('bold') if self.bold
+      str
+    end
   end
 end

data/lib/command_line_reporter.rb

@@ -11,6 +11,7 @@ module CommandLineReporter
   DEFAULTS = {
     :width => 100,
     :align => 'left',
+    :formatter => 'nested',
   }
 
   def suppress_output
@@ -36,21 +37,25 @@ module CommandLineReporter
   end
 
   def report(options = {}, &block)
-    self.formatter ||= 'nested'
+    self.formatter ||= DEFAULTS[:formatter]
     self.formatter.format(options, block)
   end
 
+  def progress(override = nil)
+    self.formatter.progress(override)
+  end
+
   def footer(options = {})
     section(:footer, options)
   end
 
   def horizontal_rule(options = {})
-    validate_options(options, :char, :width)
+    validate_options(options, :char, :width, :color, :bold)
 
     char = options[:char].is_a?(String) ? options[:char] : '-'
     width = options[:width] || DEFAULTS[:width]
 
-    puts char * width
+    aligned(char * width, :width => width, :color => options[:color], :bold => options[:bold])
   end
 
   def vertical_spacing(lines = 1)
@@ -60,7 +65,7 @@ module CommandLineReporter
   end
 
   def datetime(options = {})
-    validate_options(options, :align, :width, :format)
+    validate_options(options, :align, :width, :format, :color, :bold)
 
     format = options[:format] || '%Y-%m-%d - %l:%M:%S%p'
     align = options[:align] || DEFAULTS[:align]
@@ -70,67 +75,76 @@ module CommandLineReporter
 
     raise Exception if text.size > width
 
-    aligned(text, {:align => align, :width => width})
+    aligned(text, :align => align, :width => width, :color => options[:color], :bold => options[:bold])
   end
 
   def aligned(text, options = {})
-    validate_options(options, :align, :width)
+    validate_options(options, :align, :width, :color, :bold)
 
     align = options[:align] || DEFAULTS[:align]
     width = options[:width] || DEFAULTS[:width]
-
-    case align
-    when 'left'
-      puts text
-    when 'right'
-      puts text.rjust(width)
-    when 'center'
-      puts text.rjust((width - text.size)/2 + text.size)
-    else
-      raise ArgumentError
-    end
+    color = options[:color]
+    bold = options[:bold] || false
+
+    line = case align
+           when 'left'
+             text
+           when 'right'
+             text.rjust(width)
+           when 'center'
+             text.rjust((width - text.size)/2 + text.size)
+           else
+             raise ArgumentError
+           end
+
+    line = line.send(color) if color
+    line = line.send('bold') if bold
+
+    puts line
   end
 
   def table(options = {})
-    @table = Table.new(options)
+    @table = CommandLineReporter::Table.new(options)
     yield
     @table.output
   end
 
   def row(options = {})
-    @row = Row.new
+    @row = CommandLineReporter::Row.new(options)
     yield
     @table.add(@row)
   end
 
   def column(text, options = {})
-    col = Column.new(text, options)
+    col = CommandLineReporter::Column.new(text, options)
     @row.add(col)
   end
 
   private
 
   def section(type, options)
-    validate_options(options, :title, :width, :align, :spacing, :timestamp, :rule)
+    validate_options(options, :title, :width, :align, :spacing, :timestamp, :rule, :color, :bold)
 
     title = options[:title] || 'Report'
     width = options[:width] || DEFAULTS[:width]
     align = options[:align] || DEFAULTS[:align]
     lines = options[:spacing] || 1
+    color = options[:color]
+    bold = options[:bold] || false
 
     # This also ensures that width is a Fixnum
     raise ArgumentError if title.size > width
 
     if type == :footer
       vertical_spacing(lines)
-      horizontal_rule(:char => options[:rule], :width => width) if options[:rule]
+      horizontal_rule(:char => options[:rule], :width => width, :color => color, :bold => bold) if options[:rule]
     end
 
-    aligned(title, {:align => align, :width => width})
-    datetime(:align => align, :width => width) if options[:timestamp]
+    aligned(title, :align => align, :width => width, :color => color, :bold => bold)
+    datetime(:align => align, :width => width, :color => color, :bold => bold) if options[:timestamp]
 
     if type == :header
-      horizontal_rule(:char => options[:rule], :width => width) if options[:rule]
+      horizontal_rule(:char => options[:rule], :width => width, :color => color, :bold => bold) if options[:rule]
       vertical_spacing(lines)
     end
   end

data/lib/nested_formatter.rb

@@ -1,13 +1,17 @@
 require 'singleton'
+require 'options_validator'
+require 'colored'
 
 module CommandLineReporter
   class NestedFormatter
     include Singleton
+    include OptionsValidator
 
-    attr_accessor :indent_size, :complete_string, :message_string
+    VALID_OPTIONS = [:message, :type, :complete, :indent_size, :color, :bold]
+    attr_accessor :indent_size, :complete_string, :message_string, :color, :bold
 
     def format(options, block)
-      raise ArgumentError unless (options.keys - [:message, :type, :complete, :indent_size]).empty?
+      self.validate_options(options, *VALID_OPTIONS)
 
       indent_level :incr
 
@@ -17,15 +21,15 @@ module CommandLineReporter
       complete_str = options[:complete] || self.complete_string
 
       if options[:type] == 'inline'
-        print "#{message_str}..."
+        colorize("#{message_str}...", true, options)
       else
-        puts message_str
+        colorize(message_str, false, options)
         complete_str = padding + complete_str
       end
 
       block.call
 
-      puts complete_str
+      colorize(complete_str, false, options)
 
       indent_level :decr
     end
@@ -44,6 +48,17 @@ module CommandLineReporter
 
     private
 
+    def colorize(str, inline, options)
+      str = str.send(options[:color]) if options[:color]
+      str = str.bold if options[:bold]
+
+      if inline
+        print str
+      else
+        puts str
+      end
+    end
+
     def indent_level(value)
       case value
       when :incr

data/lib/progress_formatter.rb

@@ -1,19 +1,34 @@
 require 'singleton'
+require 'options_validator'
+require 'colored'
 
 module CommandLineReporter
   class ProgressFormatter
     include Singleton
+    include OptionsValidator
 
-    attr_accessor :indicator
+    VALID_OPTIONS = [:indicator, :color, :bold]
+    attr_accessor *VALID_OPTIONS
 
     def format(options, block)
+      self.validate_options(options, *VALID_OPTIONS)
+
       self.indicator = options[:indicator] if options[:indicator]
+      self.color = options[:color]
+      self.bold = options[:bold] || false
+
       block.call
+
       puts
     end
 
     def progress(override = nil)
-      print override || self.indicator
+      str = override || self.indicator
+
+      str = str.send(self.color) if self.color
+      str = str.send('bold') if self.bold
+
+      print str
     end
 
     def indicator