tty 0.0.10 → 0.0.11

data/README.md

@@ -16,7 +16,8 @@ Toolbox for developing CLI clients in Ruby. This library provides a fluid interf
 Jump-start development of your command line app:
 
 * Table rendering with an easy-to-use API. [status: In Progress]
-* Terminal output colorization, paging.    [status: ✔ ]
+* Terminal output colorization.            [status: ✔ ]
+* Terminal output paging.                  [status: ✔ ]
 * System & command detection utilities.    [status: In Progress]
 * Text manipulation(wrapping/truncation)   [status: In Progress]
 * Shell user interface.                    [status: In Progress]
@@ -106,22 +107,28 @@ This will use so called `basic` renderer with default options.
 However, you can include other customization options such as
 
 ```ruby
-column_widths  # array of maximum columns widths
-column_aligns  # array of cell alignments out of :left, :center and :right, default :left
-width          # constrain the table total width, otherwise dynamically calculated based on content and terminal size
-renderer       # enforce display type out of :basic, :color, :unicode, :ascii
 border         # hash of border properties out of :characters, :style, :separator keys
 border_class   # a type of border to use
-multiline      # if true will wrap text at new line or column width, when false will escape special characters
+column_widths  # array of maximum columns widths
+column_aligns  # array of cell alignments out of :left, :center and :right, default :left
 filter         # a proc object that is applied to every field in a row
+indent         # indentation applied to rendered table
+multiline      # if true will wrap text at new line or column width,
+               # when false will escape special characters
 orientation    # either :horizontal or :vertical
+padding        # array of integers to set table fields padding
+renderer       # enforce display type out of :basic, :color, :unicode, :ascii
+resize         # if true will expand/shrink table column sizes to match the width,
+               # otherwise if false rotate table vertically
+width          # constrain the table total width, otherwise dynamically
+               # calculated from content and terminal size
 ```
 
 #### Multiline
 
 Renderer options may include `multiline` parameter. The `true` value will cause the table fields wrap at their natural line breaks or in case when the column widths are set the content will wrap.
 
-```
+```ruby
 table = TTY::Table.new [ ["First", '1'], ["Multi\nLine\nContent", '2'], ["Third", '3']]
 table.render :ascii, multiline: true
 # =>
@@ -184,7 +191,7 @@ Next pass the border class to your table instance `render_with` method
 ```ruby
 table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
 table.render_with MyBorder
-
+# =>
   $header1$header2$
   $a1     $a2     $
   *       *       *
@@ -200,7 +207,7 @@ table.render do |renderer|
     mid_mid      ' '
   end
 end
-
+# =>
   header1 header2
   ======= =======
   a1      a2
@@ -214,7 +221,7 @@ table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']]
 table.render do |renderer|
   renderer.border.separator = :each_row
 end
-
+# =>
   +-------+-------+
   |header1|header2|
   +-------+-------+
@@ -258,13 +265,38 @@ table = TTY::Table.new do |t|
 end
 ```
 
-#### Style
+#### Padding
 
-To format individual fields/cells do
+By default padding is not applied. You can add `padding` to table fields like so
 
 ```ruby
-table = TTY::Table.new rows: rows
-table.render width: 40
+heaer = ['Field', 'Type', 'Null', 'Key', 'Default', 'Extra']
+rows  = [['id', 'int(11)', 'YES', 'nil', 'NULL', '']]
+table = TTY::Table.new(header, rows)
+table.render { |renderer| renderer.padding= [0,1,0,1] }
+# =>
+  +-------+---------+------+-----+---------+-------+
+  | Field | Type    | Null | Key | Default | Extra |
+  +-------+---------+------+-----+---------+-------+
+  | id    | int(11) | YES  | nil | NULL    |       |
+  +-------+---------+------+-----+---------+-------+
+```
+
+or you can set specific padding using `right`, `left`, `top`, `bottom` helpers. However, when adding top or bottom padding a `multiline` option needs to be set to `true` to allow for rows to span multiple lines. For example
+
+```ruby
+table.render { |renderer|
+  renderer.multiline = true
+  renderer.padding.top = 1
+}
+# =>
+  +-----+-------+----+---+-------+-----+
+  |     |       |    |   |       |     |
+  |Field|Type   |Null|Key|Default|Extra|
+  +-----+-------+----+---+-------+-----+
+  |     |       |    |   |       |     |
+  |id   |int(11)|YES |nil|NULL   |     |
+  +-----+-------+----+---+-------+-----+
 ```
 
 #### Filter
@@ -282,7 +314,7 @@ table.render do |renderer|
     end
   end
 end
-
+# =>
   +-------+-------+
   |header1|header2|
   +-------+-------+
@@ -292,17 +324,36 @@ end
   +-------+-------+
 ```
 
-To add background color to even fields do
+To color even fields red on green background add filter like so
 
 ```ruby
 table.render do |renderer|
-  renderer.filter = Proc.new do |val, row_index, col_index|
-    if col_index % 2 == 1
-      TTY.color.set val, :red, :on_green
+  renderer.filter = proc do |val, row_index, col_index|
+    col_index % 2 == 1 ? TTY.color.set(val, :red, :on_green) : val
   end
 end
 ```
 
+#### Width
+
+To control table's column sizes pass `width`, `resize` options. By default table's natural column widths are calculated from the content. If the total table width does not fit in terminal window then the table is rotated vertically to preserve content.
+
+The `resize` property will force the table to expand/shrink to match the terminal width or custom `width`. On its own the `width` property will not resize table but only enforce table vertical rotation if content overspills.
+
+```ruby
+header = ['h1', 'h2', 'h3']
+rows   = [['aaa1', 'aa2', 'aaaaaaa3'], ['b1', 'b2', 'b3']]
+table = TTY::Table.new header, rows
+table.render width: 80, resize: true
+# =>
+  +---------+-------+------------+
+  |h1       |h2     |h3          |
+  +---------+-------+------------+
+  |aaa1     |aa2    |aaaaaaa3    |
+  |b1       |b2     |b3          |
+  +---------+-------+------------+
+```
+
 ### Terminal
 
 To read general terminal properties you can use on of the helpers
@@ -403,15 +454,20 @@ Reading answers and converting them into required types can be done with custom
 
 ```ruby
 read_bool       # return true or false for strings such as "Yes", "No"
+read_char       # return first character
 read_date       # return date type
 read_datetime   # return datetime type
 read_email      # validate answer against email regex
+read_file       # return a File object
 read_float      # return decimal or error if cannot convert
 read_int        # return integer or error if cannot convert
 read_multiple   # return multiple line string
 read_password   # return string with echo turned off
 read_range      # return range type
+read_regex      # return regex expression
 read_string     # return string
+read_symbol     # return symbol
+read_text       # return multiline string
 ```
 
 For example, if we wanted to ask a user for a single digit in given range

data/lib/tty.rb

@@ -62,10 +62,13 @@ require 'tty/table/border/null'
 require 'tty/table/border/row_line'
 
 require 'tty/table/column_set'
+require 'tty/table/columns'
 require 'tty/table/orientation'
 require 'tty/table/orientation/horizontal'
 require 'tty/table/orientation/vertical'
 require 'tty/table/transformation'
+require 'tty/table/indentation'
+require 'tty/table/padder'
 
 require 'tty/table/operations'
 require 'tty/table/operation/alignment_set'
@@ -74,6 +77,7 @@ require 'tty/table/operation/truncation'
 require 'tty/table/operation/wrapped'
 require 'tty/table/operation/filter'
 require 'tty/table/operation/escape'
+require 'tty/table/operation/padding'
 
 module TTY
 
@@ -95,6 +99,9 @@ module TTY
   # Raised when the table orientation is unkown
   class InvalidOrientationError < ArgumentError; end
 
+  # Raised when the table cannot be resized
+  class ResizeError < ArgumentError; end
+
   # Raised when the passed in validation argument is of wrong type
   class ValidationCoercion < TypeError; end
 

data/lib/tty/shell/question.rb

@@ -153,7 +153,6 @@ module TTY
         self
       end
 
-
       # Reset question object.
       #
       # @api public
@@ -170,7 +169,7 @@ module TTY
       #
       # @api public
       def modify(*rules)
-        @modifier = Modifier.new *rules
+        @modifier = Modifier.new(*rules)
         self
       end
 
@@ -281,6 +280,7 @@ module TTY
         return default_value if !value && default?
 
         check_required value
+        return         if value.nil?
         check_valid    value unless valid_values.empty?
         within?        value
         validation.valid_value? value
@@ -293,7 +293,7 @@ module TTY
       #
       # @api private
       def check_required(value)
-        if required? && !default? && !value
+        if required? && !default? && value.nil?
           raise ArgumentRequired, 'No value provided for required'
         end
       end

data/lib/tty/shell/response.rb

@@ -46,9 +46,9 @@ module TTY
         if question.mask? && question.echo?
           reader.getc(question.mask)
         else
-          TTY.terminal.echo(question.echo) {
+          TTY.terminal.echo(question.echo) do
             question.character? ? reader.getc(question.mask) : reader.gets
-          }
+          end
         end
       end
 
@@ -59,7 +59,7 @@ module TTY
       #
       # @api public
       def read_string(error=nil)
-        question.evaluate_response String(read_input)
+        question.evaluate_response(String(read_input).strip)
       end
 
       # Read answer's first character
@@ -165,10 +165,10 @@ module TTY
       #
       # @api public
       def read_multiple
-        response = ""
+        response = ''
         loop do
           value = question.evaluate_response read_input
-          break if !value || value == ""
+          break if !value || value == ''
           next  if value !~ /\S/
           response << value
         end

data/lib/tty/table.rb

@@ -39,6 +39,20 @@ module TTY
     # @api public
     attr_reader :orientation
 
+    # The table original row count
+    #
+    # @reutrn [Integer]
+    #
+    # @api public
+    attr_reader :original_rows
+
+    # The table original column count
+    #
+    # @reutrn [Integer]
+    #
+    # @api public
+    attr_reader :original_columns
+
     # Subset of safe methods that both Array and Hash implement
     def_delegators(:data, :assoc, :flatten, :include?, :index,
                    :length, :select, :to_a, :values_at, :pretty_print, :rassoc)
@@ -100,11 +114,12 @@ module TTY
       validate_options! options
       @header        = (value = options[:header]) ? Header.new(value) : nil
       @rows          = coerce(options.fetch(:rows) { Row.new([]) })
-      @orientation   = Orientation.coerce(options.fetch(:orientation) { :horizontal })
       @rotated       = false
-      # TODO: assert that row_size is the same as column widths & aligns
+      self.orientation = options.fetch(:orientation) { :horizontal }
+
       assert_row_sizes @rows
-      @orientation.transform(self)
+      orientation.transform(self)
+
       yield_or_eval(&block) if block_given?
     end
 
@@ -149,33 +164,37 @@ module TTY
     #
     # @api private
     def rotate_vertical
-      @rows    = ([header].compact + rows).transpose.map { |row| to_row(row) }
-      @header  = [] if header
-      @rotated = true
+      @original_columns = column_size
+      @original_rows    = row_size
+      @rows             = orientation.slice(self)
+      @header           = [] if header
+      @rotated          = true
     end
 
     # Rotate the table horizontally
     #
     # @api private
     def rotate_horizontal
-      transposed = rows.transpose
-      if header && header.empty?
-        @header = transposed[0]
-        @rows   = transposed[1..-1].map { |row| to_row(row, @header) }
-      elsif rotated?
-        @rows = transposed.map { |row| to_row(row) }
+      if rotated?
+        head, body = orientation.slice(self)
+        if header && header.empty?
+          @header = head[0]
+          @rows   = body.map {|row| to_row(row, @header)}
+        else
+          @rows  = body.map { |row| to_row(row) }
+        end
       end
     end
 
     # Lookup element of the table given a row(i) and column(j)
     #
     # @api public
-    def [](i, j=false)
-      return row(i) unless j
-      if i >= 0 && j >= 0
-        rows.fetch(i) { return nil }[j]
+    def [](row_index, column_index=false)
+      return row(row_index) unless column_index
+      if row_index >= 0 && column_index >= 0
+        rows.fetch(row_index) { return nil }[column_index]
       else
-        raise TTY::Table::TupleMissing.new(i,j)
+        raise TTY::Table::TupleMissing.new(row_index, column_index)
       end
     end
     alias at        []
@@ -185,8 +204,8 @@ module TTY
     # Set table value at row(i) and column(j)
     #
     # @api private
-    def []=(i, j, val)
-      @rows[i][j] = val
+    def []=(row_index, column_index, val)
+      @rows[row_index][column_index] = val
     end
     private :[]=
 
@@ -313,6 +332,7 @@ module TTY
     # @return [Integer]
     #
     # @api public
+    # TODO: renmae to columns_size
     def column_size
       return rows[0].size if rows.size > 0
       return 0
@@ -370,6 +390,18 @@ module TTY
       render(:basic)
     end
 
+    # Return renderer for this table
+    #
+    # @param [Symbol] type
+    #   the renderer type
+    #
+    # @param [Hash] options
+    #   the renderer options
+    #
+    def renderer(type=:basic, options={})
+      @renderer ||= Renderer.select(type).new(self, options)
+    end
+
     # Render a given table. This method takes options which will be passed
     # to the renderer prior to rendering, which allows the caller to set any
     # table rendering variables.

data/lib/tty/table/column_set.rb

@@ -37,6 +37,47 @@ module TTY
         self.class.find_maximas(colcount, data)
       end
 
+      # Assert data integrity for column widths
+      #
+      # @param [Array] column_widths
+      #
+      # @param [Integer] table_widths
+      #
+      # @raise [TTY::InvalidArgument]
+      #
+      # @api public
+      def self.assert_widths(column_widths, table_widths)
+        if column_widths.empty?
+          raise InvalidArgument, 'Value for :column_widths must be a non-empty array'
+        end
+        if column_widths.size != table_widths
+          raise InvalidArgument, 'Value for :column_widths must match table column count'
+        end
+      end
+
+      # Converts column widths to array format or infers default widths
+      #
+      # @param [TTY::Table] table
+      #
+      # @param [Array, Numeric, NilClass] column_widths
+      #
+      # @return [Array[Integer]]
+      #
+      # @api public
+      def self.widths_from(table, column_widths = nil)
+        case column_widths
+        when Array
+          assert_widths(column_widths, table.column_size)
+          Array(column_widths).map(&:to_i)
+        when Numeric
+          Array.new(table.column_size, column_widths)
+        when NilClass
+          new(table).extract_widths
+        else
+          raise TypeError, 'Invalid type for column widths'
+        end
+      end
+
       private
 
       # Find maximum widths for each row and header if present.
@@ -68,7 +109,7 @@ module TTY
       #
       # @api private
       def self.find_maximum(data, index)
-        data.map { |row| (value=row.call(index)) ? value.length : 0 }.max
+        data.map { |row| (value = row.call(index)) ? value.length : 0 }.max
       end
 
     end # ColumnSet