columnist 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 35ce2268e5eb282ea238c82f068afe57dc8140e4
+  data.tar.gz: cf74dcb33851da6ae27429675ce80d06288f0dc0
+SHA512:
+  metadata.gz: a76d6cb4ee88847ed5dd3ddc465d56cb3fc6f7f886a1e4c16dc80ce787f3ec49d52e6a81ec258250d9c39bce28cab12f31073d3d328e38f478984eecd90082b5
+  data.tar.gz: e5b603a886e092c61b43472a984027e275b81195db5eff1894b533c01a32a9b17c1ba60bde9f20b2f40079c03eac9e0136c3b9b2c56946f2819a70609db89742

data/README.md

@@ -0,0 +1,150 @@
+## Columnist
+
+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:
+
+* 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
+* Capture report output as a string
+
+The latest release, thanks to a contribution from [Josh Brown](https://github.com/tobijb), allows you
+to choose between UTF8 or ASCII for drawing tables.  By default it will use UTF8 if your system
+supports it. Here is an example of output you can generate easily with "the reporter":
+
+![Screenshot](http://i.imgur.com/5izCf.png)
+
+### Installation
+
+It is up on rubygems.org so add it to your bundle in the Gemfile
+
+```bash
+gem 'columnist', '>=1.0'
+```
+
+or do it the old fashioned way:
+
+```bash
+gem install columnist
+```
+
+### Usage
+
+The gem provides a mixin that can be included in your scripts.
+
+```ruby
+require 'columnist'
+
+class MyReport
+  include Columnist
+  ...
+end
+```
+
+### [Wiki](https://github.com/alb3rtuk/columnist)
+
+The [Wiki](https://github.com/alb3rtuk/columnist) 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:
+
+* _header(hash)_ and _footer(hash)_
+  * _:title_ - The title text for the section.  _Default: 'Report'_
+  * _:width_ - The width in characters for the section.  _Default: 100_
+  * _:align_ - 'left'|'right'|'center' align the title text.  _Default: 'left'_
+  * _:spacing_ - Number of vertical lines to leave as spacing after|before the header|footer.
+    _Default: 1_
+  * _:timestamp_ - Include a line indicating the timestamp below|above the header|footer text.
+    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.
+  * 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.
+* _formatter=(string)_
+  * Factory method indicating the formatter you want your application to use.  At present the 2
+    formatters are (_Default: 'nested'_):
+  * 'progress' - Use the progress formatter
+  * 'nested' - Use the nested (or documentation) 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
+    * _:encoding_ - :ascii or :unicode (default unicode)
+  * The second argument is a block which includes calls the to the _row_ method
+* _row {block}_
+  * _: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
+* _suppress_output_ - Suppresses output stream that goes to STDOUT
+* _capture_output_ - Captures all of the output stream to a string and restores output to STDOUT
+* _restore_output_ - Restores the output stream to STDOUT
+
+### To Do
+
+* Add a formatter that supports html output
+* Add the ability for a column to span across others in a table
+
+### Contributors
+
+* [Josh Brown](https://github.com/tobijb) added the ability to encode tables in either ascii or utf8
+* [Stefan Frank](https://github.com/mugwump) for raising the issue that he could not capture report
+  output in a variable as a string
+* [Mike Gunderloy](https://github.com/ffmike) for suggesting the need for suppressing output and
+  putting together a fantastic pull request and discussion
+* [Jason Rogers](https://github.com/jacaetevha) and [Peter Suschlik](https://github.com/splattael)
+  for their contributions as well on items I missed
+
+### License
+
+Copyright (c) 2011-2014 Albert Rannetsperger
+
+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/lib/columnist/column.rb

@@ -0,0 +1,99 @@
+require 'colored'
+
+module Columnist
+    class Column
+        include OptionsValidator
+
+        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)
+            self.text = text.to_s
+            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+$/)
+        end
+
+        def size
+            self.width - 2 * self.padding
+        end
+
+        def required_width
+            self.text.to_s.size + 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) }
+            end
+        end
+
+        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 = str.empty? ? blank_cell : aligned_cell(str)
+            padding_str = ' ' * self.padding
+            padding_str + colorize(cell) + padding_str
+        end
+
+        def blank_cell
+            ' ' * self.size
+        end
+
+        def aligned_cell(str)
+            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
+
+        def colorize(str)
+            str = str.send('bold') if self.bold
+            case self.color
+                when 'red'
+                    return "\x1B[38;5;9m#{str}\x1B[38;5;256m"
+                when 'green'
+                    return "\x1B[38;5;10m#{str}\x1B[38;5;256m"
+                when 'yellow'
+                    return "\x1B[38;5;11m#{str}\x1B[38;5;256m"
+                when 'blue'
+                    return "\x1B[38;5;33m#{str}\x1B[38;5;256m"
+                when 'magenta'
+                    return "\x1B[38;5;13m#{str}\x1B[38;5;256m"
+                when 'cyan'
+                    return "\x1B[38;5;14m#{str}\x1B[38;5;256m"
+                when 'gray'
+                    return "\x1B[38;5;240m#{str}\x1B[38;5;256m"
+                when 'white'
+                    return "\x1B[38;5;255m#{str}\x1B[38;5;256m"
+                when 'black'
+                    return "\x1B[38;5;0m#{str}\x1B[38;5;256m"
+            end
+            if is_number?(self.color)
+                str = "\x1B[38;5;#{self.color}m#{str}\x1B[38;5;256m"
+            end
+            str
+        end
+
+        def is_number?(str)
+            true if Integer(str) rescue false
+        end
+    end
+end

data/lib/columnist/formatter/nested.rb

@@ -0,0 +1,70 @@
+require 'singleton'
+require 'colored'
+
+module Columnist
+  class NestedFormatter
+    include Singleton
+    include OptionsValidator
+
+    VALID_OPTIONS = [:message, :type, :complete, :indent_size, :color, :bold]
+    attr_accessor :indent_size, :complete_string, :message_string, :color, :bold
+
+    def format(options, block)
+      self.validate_options(options, *VALID_OPTIONS)
+
+      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'
+        colorize("#{message_str}...", true, options)
+      else
+        colorize(message_str, false, options)
+        complete_str = padding + complete_str
+      end
+
+      block.call
+
+      colorize(complete_str, false, options)
+
+      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 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
+        @indent_level = (@indent_level) ? @indent_level + 1 : 0
+      when :decr
+        @indent_level -= 1
+      end
+    end
+  end
+end

data/lib/columnist/formatter/progress.rb

@@ -0,0 +1,37 @@
+require 'singleton'
+require 'colored'
+
+module Columnist
+  class ProgressFormatter
+    include Singleton
+    include OptionsValidator
+
+    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)
+      str = override || self.indicator
+
+      str = str.send(self.color) if self.color
+      str = str.send('bold') if self.bold
+
+      print str
+    end
+
+    def indicator
+      @indicator ||= '.'
+    end
+  end
+end

data/lib/columnist/options_validator.rb

@@ -0,0 +1,5 @@
+module OptionsValidator
+  def validate_options(provided, *allowed_keys)
+    raise(ArgumentError, "Valid options: #{allowed_keys}") unless (provided.keys - allowed_keys).empty?
+  end
+end

data/lib/columnist/row.rb

@@ -0,0 +1,83 @@
+module Columnist
+    class Row
+        include OptionsValidator
+
+        VALID_OPTIONS = [:header, :color, :border_color, :bold, :encoding]
+        attr_accessor :columns, :border, *VALID_OPTIONS
+
+        def initialize(options = {})
+            self.validate_options(options, *VALID_OPTIONS)
+
+            self.columns = []
+            self.border = false
+            self.header = options[:header] || false
+            self.color = options[:color]
+            self.border_color = options[:border_color]
+            self.bold = options[:bold] || false
+            self.encoding = options[:encoding] || :unicode
+        end
+
+        def add(column)
+            if column.color.nil? && self.color
+                column.color = self.color
+            end
+
+            if self.bold || self.header
+                column.bold = true
+            end
+
+            self.columns << column
+        end
+
+        def output
+            screen_count.times do |sr|
+                border_char = use_utf8? ? "\u2503" : '|'
+                border_char = border_char.send(self.border_color) if self.border_color
+
+                line = (self.border) ? "#{border_char} " : ''
+
+                self.columns.size.times do |mc|
+                    col = self.columns[mc]
+                    # Account for the fact that some columns will have more screen rows than their
+                    # counterparts in the row.  An example being:
+                    # c1 = Column.new('x' * 50, :width => 10)
+                    # c2 = Column.new('x' * 20, :width => 10)
+                    #
+                    # c1.screen_rows.size == 5
+                    # c2.screen_rows.size == 2
+                    #
+                    # So when we don't have a screen row for c2 we need to fill the screen with the
+                    # proper number of blanks so the layout looks like (parenthesis on the right just
+                    # indicate screen row index)
+                    #
+                    # +-------------+------------+
+                    # | xxxxxxxxxxx | xxxxxxxxxx | (0)
+                    # | xxxxxxxxxxx | xxxxxxxxxx | (1)
+                    # | xxxxxxxxxxx |            | (2)
+                    # | xxxxxxxxxxx |            | (3)
+                    # | xxxxxxxxxxx |            | (4)
+                    # +-------------+------------+
+                    if col.screen_rows[sr].nil?
+                        line << ' ' * col.width
+                    else
+                        line << self.columns[mc].screen_rows[sr]
+                    end
+
+                    line << ' ' + ((self.border) ? "#{border_char} " : '')
+                end
+
+                puts line
+            end
+        end
+
+        private
+
+        def screen_count
+            @sc ||= self.columns.inject(0) { |max, column| column.screen_rows.size > max ? column.screen_rows.size : max }
+        end
+
+        def use_utf8?
+            self.encoding == :unicode && "\u2501" != "u2501"
+        end
+    end
+end

data/lib/columnist/table.rb

@@ -0,0 +1,133 @@
+module Columnist
+    class Table
+        include OptionsValidator
+
+        VALID_OPTIONS = [:border, :border_color, :width, :encoding]
+        attr_accessor :rows, *VALID_OPTIONS
+
+        def initialize(options = {})
+            self.validate_options(options, *VALID_OPTIONS)
+
+            self.border = options[:border] || false
+            self.border_color = options[:border_color] || false
+            self.width = options[:width] || false
+            self.encoding = options[:encoding] || Columnist::DEFAULTS[:encoding]
+
+            @rows = []
+
+            raise ArgumentError, "Invalid encoding" unless [:ascii, :unicode].include? self.encoding
+        end
+
+        def add(row)
+            # Inheritance from the table
+            row.border = self.border
+            row.border_color = self.border_color
+
+            # Inherit properties from the appropriate row
+            inherit_column_attrs(row) if self.rows[0]
+
+            self.rows << row
+        end
+
+        def output
+            return if self.rows.size == 0 # we got here with nothing to print to the screen
+            auto_adjust_widths if self.width == :auto
+
+            puts separator('first') if self.border
+            self.rows.each_with_index do |row, index|
+                row.output
+                puts separator('middle') if self.border && (index != self.rows.size - 1)
+            end
+            puts separator('last') if self.border
+        end
+
+        def auto_adjust_widths
+            column_widths = []
+
+            self.rows.each do |row|
+                row.columns.each_with_index do |col, i|
+                    column_widths[i] = [col.required_width, (column_widths[i] || 0)].max
+                end
+            end
+
+            self.rows.each do |row|
+                row.columns.each_with_index do |col, i|
+                    col.width = column_widths[i]
+                end
+            end
+        end
+
+        private
+
+        def separator(type = 'middle')
+            left, center, right, bar = use_utf8? ? utf8_separator(type) : ascii_separator
+
+            separator_str = left + self.rows[0].columns.map { |c| bar * (c.width + 2) }.join(center) + right
+            separator_str.send(self.border_color) if self.border_color
+        end
+
+        def use_utf8?
+            self.encoding == :unicode && "\u2501" != "u2501"
+        end
+
+        def ascii_separator
+            left = right = center = '+'
+            bar = '-'
+            [left, right, center, bar]
+        end
+
+        def utf8_separator(type)
+            bar = "\u2501"
+
+            left, center, right = case type
+                                      when 'first'
+                                          ["\u250F", "\u2533", "\u2513"]
+                                      when 'middle'
+                                          ["\u2523", "\u254A", "\u252B"]
+                                      when 'last'
+                                          ["\u2517", "\u253B", "\u251B"]
+                                  end
+
+            [left, center, right, bar]
+        end
+
+        def inherit_column_attrs(row)
+            row.columns.each_with_index do |c, i|
+                use_positional_attrs(c, i)
+                use_color(row, c, i)
+                use_bold(row, c, i)
+            end
+        end
+
+        def use_positional_attrs(c, i)
+            # The positional attributes are always required to inheret to make sure the table
+            # displays properly
+            %w{align padding width}.each do |attr|
+                val = self.rows[0].columns[i].send(attr)
+                c.send(attr + "=", val)
+            end
+        end
+
+        def inherit_from
+            self.rows[0].header ? 1 : 0
+        end
+
+        def use_color(row, c, i)
+            if c.color
+                # keep default
+            elsif row.color
+                c.color = row.color
+            elsif inherit_from != 1
+                c.color = self.rows[inherit_from].columns[i].color
+            end
+        end
+
+        def use_bold(row, c, i)
+            if row.bold
+                c.bold = row.bold
+            elsif inherit_from != 1
+                c.bold = self.rows[inherit_from].columns[i].bold
+            end
+        end
+    end
+end