tty 0.0.7 → 0.0.8

data/.travis.yml

@@ -16,5 +16,4 @@ matrix:
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head
-    - rvm: jruby-19mode
     - rvm: rbx-19mode

data/README.md

@@ -1,6 +1,9 @@
 # TTY
-[![Build Status](https://secure.travis-ci.org/peter-murach/tty.png?branch=master)][travis] [![Code Climate](https://codeclimate.com/badge.png)][codeclimate]
+[![Gem Version](https://badge.fury.io/rb/tty.png)][gem]
+[![Build Status](https://secure.travis-ci.org/peter-murach/tty.png?branch=master)][travis]
+[![Code Climate](https://codeclimate.com/github/peter-murach/tty.png)][codeclimate]
 
+[gem]: http://badge.fury.io/rb/tty
 [travis]: http://travis-ci.org/peter-murach/tty
 [codeclimate]: https://codeclimate.com/github/peter-murach/tty
 
@@ -10,14 +13,16 @@ Toolbox for developing CLI clients in Ruby. This library provides a fluid interf
 
 Jump-start development of your command line app:
 
-* Fully customizable table rendering with an easy-to-use API. (status: In Progress)
-* Terminal output colorization.          (status: DONE)
-* Terminal & System detection utilities. (status: In Progress)
-* Text alignment/padding/indentation.    (status: In Progress)
-* Shell user interface.                  (status: In Progress)
-* File diffs.                            (status: TODO)
-* Progress bar.                          (status: TODO)
-* Configuration file management.         (status: TODO)
+* Table rendering with an easy-to-use API  [status: In Progress]
+* Terminal output colorization.            [status: ✔ ]
+* Terminal & System detection utilities.   [status: In Progress]
+* Text manipulation(wrapping/truncation)   [status: In Progress]
+* Shell user interface.                    [status: In Progress]
+* File diffs.                              [status: TODO]
+* Progress bar.                            [status: TODO]
+* Configuration file management.           [status: TODO]
+* Logging                                  [status: In Progress]
+* Plugin ecosystem                         [status: TODO]
 * Fully tested with major ruby interpreters.
 * No dependencies to allow for easy gem vendoring.
 
@@ -45,7 +50,6 @@ To instantiate table pass 2-dimensional array:
   table = TTY::Table[['a1', 'a2'], ['b1', 'b2']]
   table = TTY::Table.new [['a1', 'a2'], ['b1', 'b2']]
   table = TTY::Table.new rows: [['a1', 'a2'], ['b1', 'b2']]
-
   table = TTY::Table.new ['h1', 'h2'], [['a1', 'a2'], ['b1', 'b2']]
   table = TTY::Table.new header: ['h1', 'h2'], rows: [['a1', 'a2'], ['b1', 'b2']]
 ```
@@ -63,6 +67,8 @@ Apart from `rows` and `header`, you can provide other customization options such
   column_aligns   # array of cell alignments out of :left, :center and :right
   renderer        # enforce display type out of :basic, :color, :unicode, :ascii
   orientation     # either :horizontal or :vertical
+  border          # hash of border properties out of :characters, :style, :separator keys
+  width           # constrain the table total width, otherwise dynamically calculated based on content and terminal size
 ```
 
 Table behaves like an Array so `<<`, `each` and familiar methods can be used
@@ -73,12 +79,15 @@ Table behaves like an Array so `<<`, `each` and familiar methods can be used
   table << ['a1', 'a2'] << ['b1', 'b2']  # chain rows assignment
 
   table.each { |row| ... }  # iterate over rows
+  table.each_with_index     # iterate over each element with row and column index
   table[i, j]               # return element at row(i) and column(j)
   table.row(i) { ... }      # return array for row(i)
   table.column(j) { ... }   # return array for column(j)
+  table.column(name)        # return array for column(name), name of header
   table.row_size            # return row size
   table.column_size         # return column size
   table.size                # return an array of [row_size, column_size]
+  table.border              # specify border properties
 ```
 
 or pass your rows in a block
@@ -99,7 +108,9 @@ And then to print do
   b1  b2  b3
 ```
 
-To print border around data table you need to specify `renderer` type out of `basic`, `ascii`, `unicode`. For instance to output unicode border:
+#### Border
+
+To print border around data table you need to specify `renderer` type out of `basic`, `ascii`, `unicode`. By default `basic` is used. For instance, to output unicode border:
 
 ```
   table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2'], renderer: 'unicode'
@@ -113,26 +124,132 @@ To print border around data table you need to specify `renderer` type out of `ba
   └───────┴───────┘
 ```
 
-You can also create your own custom border by subclassing `TTY::Table::Border`
+You can also create your own custom border by subclassing `TTY::Table::Border` and implementing the `def_border` method using internal DSL methods like so:
 
 ```ruby
   class MyBorder < TTY::Table::Border
     def_border do
-      {
-        'bottom'       => ' ',
-        'bottom_mid'   => '*',
-        'bottom_left'  => '*',
-        'bottom_right' => '*',
-        'left'         => '$',
-        'right'        => '$'
-      }
+      left         '$'
+      center       '$'
+      right        '$'
+      bottom       ' '
+      bottom_mid   '*'
+      bottom_left  '*'
+      bottom_right '*'
     end
   end
 ```
-Next pass the border to your table
+
+Next pass the border class to your instantiated table
 
 ```ruby
+  table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
   table.renders_with MyBorder
+  table.to_s
+
+  $header1$header2$
+  $a1     $a2     $
+  *       *       *
+```
+
+Finally, if you want to introduce slight modifications to the predefined border types, you can use table `border` helper like so
+
+```ruby
+  table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
+  table.border do
+    mid          '='
+    mid_mid      ' '
+  end
+
+  table.to_s
+
+  header1 header2
+  ======= =======
+  a1      a2
+  b1      b2
+```
+
+In addition to specifying border characters you can force table to render separator line on each row like:
+
+```ruby
+  table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']]
+  table.border.separator = :each_row
+  table.to_s
+
+  +-------+-------+
+  |header1|header2|
+  +-------+-------+
+  |a1     |a2     |
+  +-------+-------+
+  |b1     |b2     |
+  +-------+-------+
+```
+
+Also to change the display color of your border do:
+
+```ruby
+  table.border.style = :red
+```
+
+#### Alignment
+
+All columns are left aligned by default. You can enforce per column alignment by passing `column_aligns` option like so
+
+```ruby
+  rows = [['a1', 'a2'], ['b1', 'b2']
+  table = TTY::Table.new rows: rows, column_aligns: [:center, :right]
+```
+
+To align a single column do
+
+```ruby
+  table.align_column(1, :right)
+```
+
+If you require a more granular alignment you can align individual fields in a row by passing `align` option
+
+```ruby
+  table = TTY::Table.new do |t|
+    t << ['a1', 'a2', 'a3']
+    t << ['b1', {:value => 'b2', :align => :right}, 'b3']
+    t << ['c1', 'c2', {:value => 'c3', :align => :center}]
+  end
+```
+
+#### Style
+
+To format individual fields/cells do
+
+```ruby
+  table = TTY::Table.new rows: rows, width: 40
+```
+
+#### Filter
+
+You can define filters that will modify individual table fields value before they are rendered. A filter can be a callable such as proc. Here's an example that formats
+
+```ruby
+  table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
+  table.filter = Proc.new do |val, row_index, col_index|
+    if col_index == 1 and !(row_index == 0)
+      val.capitalize
+    end
+  end
+  table.to_s
+
+  +-------+-------+
+  |header1|header2|
+  +-------+-------+
+  |a1     |A2     |
+  +-------+-------+
+  |b1     |B2     |
+  +-------+-------+
+
+```
+
+To add background color to even fields do
+
+```ruby
 ```
 
 ### Terminal
@@ -241,8 +358,9 @@ on the other hand, if we are interested in range answer then
 ### System
 
 ```ruby
-  TTY::System.unix?      # => true
-  TTY::System.windows?   # => false
+  TTY::System.unix?       # => true
+  TTY::System.windows?    # => false
+  TTY::System.which(cmd)  # full path to executable if found, nil otherwise
 ```
 
 ## Contributing

data/benchmarks/table.rb

@@ -13,6 +13,7 @@ rows          = (1..100).map { |n| ["row#{n}", "red"] }
 table         = TTY::Table.new(header, rows)
 table_ascii   = TTY::Table.new(header, rows, :renderer => :ascii)
 table_unicode = TTY::Table.new(header, rows, :renderer => :unicode)
+table_color   = TTY::Table.new(header, rows, :renderer => :ascii, :border => { :style => :red })
 
 Benchmark.ips do |r|
 
@@ -32,4 +33,8 @@ Benchmark.ips do |r|
     table_unicode.to_s
   end
 
+  r.report("TTY Color #to_s") do
+    table_color.to_s
+  end
+
 end

data/lib/tty/logger.rb

@@ -0,0 +1,71 @@
+# -*- encoding: utf-8 -*-
+
+module TTY
+
+  # A class providing logging system
+  class Logger
+    include TTY::Equatable
+
+    ALL       = 0
+    INFO      = 1
+    DEBUG     = 2
+    WARN      = 3
+    ERROR     = 4
+    FATAL     = 5
+    OFF       = 6
+
+    MAX_LEVELS = 7
+
+    attr_reader :namespace
+
+    attr_reader :level
+
+    attr_reader :output
+
+    attr_reader :timestamp_format
+
+    # Initialize a Logger
+    #
+    # @param [String] name
+    #
+    # @param [Hash] options
+    #
+    # @option options [String] :output
+    #
+    # @api public
+    def initialize(options={})
+      @namespace = options.fetch(:namespace) { raise ArgumentError, "Logger must have namespace", caller }
+      @output = options.fetch(:output) { $stderr }
+      @level  = options.fetch(:level) { ALL }
+      @timestamp_format = options.fetch(:timestamp_format) { '%Y-%m-%d %T' }
+    end
+
+    def level=(level)
+      validate_level(level)
+      @level = level
+    end
+
+    # @api public
+    def timestamp
+      Time.now.strftime(timestamp_format)
+    end
+
+    def validate_level(level)
+      unless valid_level?(level)
+        raise ArgumentError, "Log level must be 0..#{MAX_LEVELS}", caller
+      end
+    end
+
+    def self.valid_level?(level)
+      !level.nil? && level.kind_of?(Numeric) && level >= ALL && level <= OFF
+    end
+
+    # Print formatted log to output
+    #
+    # @api public
+    def log(message)
+      output.print timestamp + ' - ' + message
+    end
+
+  end # Logger
+end # TTY

data/lib/tty/support/equatable.rb

@@ -85,8 +85,9 @@ module TTY
     # @api private
     def define_compare
       define_method(:compare?) do |comparator, other|
-        attrs = comparison_attrs || []
-        !attrs.find { |attr| send(attr).send(comparator, other.send(attr)) }
+        klass = self.class
+        attrs = klass.comparison_attrs || []
+        attrs.all? { |attr| send(attr).send(comparator, other.send(attr)) }
       end
     end
 
@@ -142,6 +143,9 @@ module TTY
       #
       # @api public
       def ==(other)
+        print '== '
+        p self
+        p other
         return false unless self.class <=> other.class
         compare?(__method__, other)
       end

data/lib/tty/system/which.rb

@@ -0,0 +1,41 @@
+# -*- encoding: utf-8 -*-
+
+module TTY
+  class System
+
+    # A class responsible for finding an executable in the PATH
+    class Which
+
+      # Find an executable in the PATH
+      #
+      # @param [String] command
+      #   the command to search in the PATH
+      #
+      # @example
+      #   which("ruby")  # => /usr/local/bin/ruby
+      #
+      # @return [String]
+      #   the full path to executable if found, `nil` otherwise
+      #
+      # @api public
+      def which(command)
+        exts = ENV['PATHEXT'] ? ENV['PATHEXT'].split(';') : ['']
+        default_system_path.each do |path|
+          exts.each do |ext|
+            exec = File.join("#{path}", "#{command}#{ext}")
+            return exec if File.executable? exec
+          end
+        end
+        return nil
+      end
+
+      # Find default system paths
+      #
+      # @api private
+      def default_system_path
+        ENV['PATH'].split(File::PATH_SEPARATOR)
+      end
+
+    end # Which
+  end # System
+end # TTY

data/lib/tty/system.rb

@@ -25,6 +25,14 @@ module TTY
         RbConfig::CONFIG['host_os'] =~ /(aix|darwin|linux|(net|free|open)bsd|cygwin|solaris|irix|hpux)/i
       end
 
+      # Find an executable in the PATH
+      #
+      # @see TTY::System::Which
+      #
+      # @api public
+      def which(command)
+        Which.new(command)
+      end
     end
 
   end # System

data/lib/tty/table/border/ascii.rb

@@ -8,22 +8,21 @@ module TTY
       class ASCII < Border
 
         def_border do
-        {
-          'top'          => '-',
-          'top_mid'      => '+',
-          'top_left'     => '+',
-          'top_right'    => '+',
-          'bottom'       => '-',
-          'bottom_mid'   => '+',
-          'bottom_left'  => '+',
-          'bottom_right' => '+',
-          'mid'          => '-',
-          'mid_mid'      => '+',
-          'mid_left'     => '+',
-          'mid_right'    => '+',
-          'left'         => '|',
-          'right'        => '|'
-        }
+          top           '-'
+          top_mid       '+'
+          top_left      '+'
+          top_right     '+'
+          bottom        '-'
+          bottom_mid    '+'
+          bottom_left   '+'
+          bottom_right  '+'
+          mid           '-'
+          mid_mid       '+'
+          mid_left      '+'
+          mid_right     '+'
+          left          '|'
+          center        '|'
+          right         '|'
         end
 
       end # ASCII

data/lib/tty/table/border/null.rb

@@ -7,18 +7,23 @@ module TTY
       # A class that represents no border.
       class Null < Border
 
+        def_border do
+          center SPACE_CHAR
+        end
+
         # A stub top line
         #
         # @api private
         def top_line
-          nil
+          border ? super : nil
         end
 
         # A stub separator line
         #
         # @api private
         def separator
-          nil
+          return [] if border.separator == EACH_ROW
+          border ? super : nil
         end
 
         # A line spanning all columns delemited by space character.
@@ -27,14 +32,14 @@ module TTY
         #
         # @api private
         def row_line
-          row.join(' ')
+          (border && !border.characters.empty?) ? super : row.join(SPACE_CHAR)
         end
 
         # A stub bottom line
         #
         # @api private
         def bottom_line
-          nil
+          border ? super : nil
         end
 
       end # Null

data/lib/tty/table/border/unicode.rb

@@ -8,22 +8,21 @@ module TTY
       class Unicode < Border
 
         def_border do
-        {
-          'top'          => '─',
-          'top_mid'      => '┬',
-          'top_left'     => '┌',
-          'top_right'    => '┐',
-          'bottom'       => '─',
-          'bottom_mid'   => '┴',
-          'bottom_left'  => '└',
-          'bottom_right' => '┘',
-          'mid'          => '─',
-          'mid_mid'      => '┼',
-          'mid_left'     => '├',
-          'mid_right'    => '┤',
-          'left'         => '│',
-          'right'        => '│'
-        }
+          top          '─'
+          top_mid      '┬'
+          top_left     '┌'
+          top_right    '┐'
+          bottom       '─'
+          bottom_mid   '┴'
+          bottom_left  '└'
+          bottom_right '┘'
+          mid          '─'
+          mid_mid      '┼'
+          mid_left     '├'
+          mid_right    '┤'
+          left         '│'
+          center       '│'
+          right        '│'
         end
 
       end # Unicode

data/lib/tty/table/border.rb

@@ -6,6 +6,14 @@ module TTY
     # Abstract base class that is responsible for building the table border.
     class Border
       include Unicode
+      include TTY::Equatable
+
+      EMPTY_CHAR = ''.freeze
+
+      SPACE_CHAR = ' '.freeze
+
+      # Represent a separtor on each row
+      EACH_ROW = :each_row
 
       # The row cell widths
       #
@@ -19,6 +27,9 @@ module TTY
       attr_reader :row
       private :row
 
+      # The table custom border characters
+      attr_reader :border
+
       class << self
         # Store characters for border
         #
@@ -28,23 +39,36 @@ module TTY
 
       # Instantiate a new object
       #
+      # @param [Array] row
+      #
+      # @param [BorderOptions] options
+      #
       # @return [Object]
       #
       # @api private
-      def initialize(row=nil)
+      def initialize(row, options=nil)
         if self.class == Border
           raise NotImplementedError, "#{self} is an abstract class"
         else
           @row = row
           @widths = row.map { |cell| cell.chars.to_a.size }
+          @border = TTY::Table::BorderOptions.from options
         end
       end
 
       # Define border characters
       #
+      # @param [Hash] characters
+      #   the border characters
+      #
+      # @return [Hash]
+      #
       # @api public
-      def self.def_border(&block)
-        @characters = block
+      def self.def_border(characters=(not_set=true), &block)
+        return self.characters = characters if !not_set
+
+        dsl = TTY::Table::BorderDSL.new(&block)
+        self.characters = dsl.characters
       end
 
       # Retrive individula character by type
@@ -56,7 +80,31 @@ module TTY
       #
       # @api private
       def [](type)
-        self.class.characters.call[type] || ''
+        characters = self.class.characters
+        chars = border.nil? ? characters : characters.merge(border.characters)
+        chars[type] || EMPTY_CHAR
+      end
+
+      # Check if border color is set
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def color?
+        border && border.style
+      end
+
+      # Set color on characters
+      #
+      # @param [Symbol] color
+      #
+      # @param [Array[String]] array of strings
+      #
+      # @return [Array[String]]
+      #
+      # @api public
+      def self.set_color(color, *strings)
+        strings.map { |string| TTY.terminal.color.set(string, color) }
       end
 
       # A line spanning all columns marking top of a table.
@@ -83,7 +131,15 @@ module TTY
       #
       # @api private
       def row_line
-        result = self['left'] + row.join(self['right']) + self['right']
+        right_char  = self['right']
+        left_char   = self['left']
+        center_char = self['center']
+
+        if color?
+          right_char, center_char, left_char = Border.set_color(border.style, right_char, center_char, left_char)
+        end
+
+        result = left_char + row.join(center_char) + right_char
         result.empty? ? nil : result
       end
 
@@ -106,10 +162,14 @@ module TTY
       # @api private
       def render(type)
         type = type.to_s
-        render_line self[type],
-          self["#{type}_left"]  || self[type],
-          self["#{type}_right"] || self[type],
-          self["#{type}_mid"]
+        border_char = self[type]
+        line = render_line(border_char,
+          self["#{type}_left"]  || border_char,
+          self["#{type}_right"] || border_char,
+          self["#{type}_mid"])
+
+        line = Border.set_color(border.style, line) if color?
+        line
       end
 
       # Generate a border string