tty 0.0.6 → 0.0.7

data/README.md

@@ -50,12 +50,19 @@ To instantiate table pass 2-dimensional array:
   table = TTY::Table.new header: ['h1', 'h2'], rows: [['a1', 'a2'], ['b1', 'b2']]
 ```
 
+or cross header with rows inside a hash like so
+
+```ruby
+  table = TTY::Table.new [{'h1' => ['a1', 'a2'], 'h2' => ['b1', 'b2']}]
+```
+
 Apart from `rows` and `header`, you can provide other customization options such as
 
 ```ruby
-  column_widths   # enforce maximum columns widths
+  column_widths   # array of maximum columns widths
   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
 ```
 
 Table behaves like an Array so `<<`, `each` and familiar methods can be used
@@ -106,13 +113,38 @@ 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`
+
+```ruby
+  class MyBorder < TTY::Table::Border
+    def_border do
+      {
+        'bottom'       => ' ',
+        'bottom_mid'   => '*',
+        'bottom_left'  => '*',
+        'bottom_right' => '*',
+        'left'         => '$',
+        'right'        => '$'
+      }
+    end
+  end
+```
+Next pass the border to your table
+
+```ruby
+  table.renders_with MyBorder
+```
+
 ### Terminal
 
+To read general terminal properties you can use on of the helpers
+
 ```ruby
   term = TTY::Terminal.new
-  term.width    # => 140
-  term.height   # =>  60
-  term.color?   # => true or false
+  term.width              # => 140
+  term.height             # =>  60
+  term.color?             # => true or false
+  term.echo(false) { }    # switch off echo for the block
 ```
 
 To colorize your output do
@@ -127,6 +159,19 @@ To colorize your output do
 
 Main responsibility is to interact with the prompt and provide convenience methods.
 
+Available methods are
+
+```ruby
+  shell = TTY::Shell.new
+  shell.ask          # print question
+  shell.read         # read from stdin
+  shell.say          # print message to stdout
+  shell.confirm      # print message(s) in green
+  shell.warn         # print message(s) in yellow
+  shell.error        # print message(s) in red
+  shell.print_table  # print table to stdout
+```
+
 In order to ask question and parse answers:
 
 ```ruby
@@ -137,12 +182,16 @@ In order to ask question and parse answers:
 The library provides small DSL to help with parsing and asking precise questions
 
 ```ruby
-  default     # default value used if none is provided
   argument    # :required or :optional
+  character   # turn character based input, otherwise line (default: false)
+  clean       # reset question
+  default     # default value used if none is provided
+  echo        # turn echo on and off (default: true)
+  mask        # mask characters i.e '****' (default: false)
+  modify      # apply answer modification :upcase, :downcase, :trim, :chomp etc..
+  range       # specify range '0-9', '0..9', '0...9' or negative '-1..-9'
   validate    # regex against which stdin input is checked
   valid       # a list of expected valid options
-  modify      # apply answer modification :upcase, :downcase, :trim, :chomp etc..
-  clean       # reset question
 ```
 
 You can chain question methods or configure them inside a block
@@ -162,14 +211,31 @@ You can chain question methods or configure them inside a block
 Reading answers and converting them into required types can be done with custom readers
 
 ```ruby
-  read_string     # return string
   read_bool       # return true or false for strings such as "Yes", "No"
-  read_int        # return integer or error if cannot convert
-  read_float      # return decimal or error if cannot convert
   read_date       # return date type
   read_datetime   # return datetime type
-  read_multiple   # return multiple line string
   read_email      # validate answer against email regex
+  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_string     # return string
+```
+
+For example, if we wanted to ask a user for a single digit in given range
+
+```ruby
+  ask("Provide number in range: 0-9") do
+    range '0-9'
+    on_error :retry
+  end.read_int
+```
+
+on the other hand, if we are interested in range answer then
+
+```ruby
+  ask("Provide range of numbers?").read_range
 ```
 
 ### System
@@ -189,4 +255,4 @@ Reading answers and converting them into required types can be done with custom
 
 ## Copyright
 
-Copyright (c) 2012 Piotr Murach. See LICENSE for further details.
+Copyright (c) 2012-2013 Piotr Murach. See LICENSE for further details.

data/benchmarks/shell.rb

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+
+# Benchmark speed of shell operations
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+
+require 'tty'
+require 'benchmark'
+require 'benchmark/ips'
+require 'stringio'
+
+input  = ::StringIO.new
+output = ::StringIO.new
+shell  = TTY::Shell.new(input, output)
+
+Benchmark.ips do |r|
+
+  r.report("Ruby #puts") do
+    output.puts "What is your name?"
+  end
+
+  r.report("TTY #ask") do
+    shell.ask("What is your name?")
+  end
+
+end

data/benchmarks/table.rb

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+
+# Benchmark speed of table operations
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+
+require 'tty'
+require 'benchmark'
+require 'benchmark/ips'
+
+header        = [:name, :color]
+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)
+
+Benchmark.ips do |r|
+
+  r.report("Ruby #to_s") do
+    rows.to_s
+  end
+
+  r.report("TTY #to_s") do
+    table.to_s
+  end
+
+  r.report("TTY ASCII #to_s") do
+    table_ascii.to_s
+  end
+
+  r.report("TTY Unicode #to_s") do
+    table_unicode.to_s
+  end
+
+end

data/lib/tty.rb

@@ -10,16 +10,32 @@ require 'tty/support/equatable'
 require 'tty/support/unicode'
 
 require 'tty/terminal'
-require 'tty/terminal/color'
 require 'tty/system'
 require 'tty/table'
+require 'tty/text'
 require 'tty/vector'
 require 'tty/shell'
+require 'tty/coercer'
+
+require 'tty/coercer/range'
+require 'tty/coercer/integer'
+require 'tty/coercer/float'
+require 'tty/coercer/boolean'
 
+require 'tty/shell/response_delegation'
 require 'tty/shell/question'
 require 'tty/shell/question/validation'
 require 'tty/shell/question/modifier'
 require 'tty/shell/statement'
+require 'tty/shell/reader'
+require 'tty/shell/response'
+
+require 'tty/terminal/color'
+require 'tty/terminal/echo'
+require 'tty/terminal/home'
+
+require 'tty/text/wrapping'
+require 'tty/text/truncation'
 
 require 'tty/table/border'
 require 'tty/table/border/unicode'
@@ -27,6 +43,9 @@ require 'tty/table/border/ascii'
 require 'tty/table/border/null'
 
 require 'tty/table/column_set'
+require 'tty/table/orientation'
+require 'tty/table/orientation/horizontal'
+require 'tty/table/orientation/vertical'
 
 require 'tty/table/operation/alignment_set'
 require 'tty/table/operation/alignment'
@@ -47,6 +66,9 @@ module TTY
   # Raised when the argument is not expected
   class InvalidArgument < ArgumentError; end
 
+  # Raised when the table orientation is unkown
+  class InvalidOrientationError < ArgumentError; end
+
   # Raised when the passed in validation argument is of wrong type
   class ValidationCoercion < TypeError; end
 

data/lib/tty/coercer.rb

@@ -0,0 +1,13 @@
+# -*- encoding: utf-8 -*-
+
+module TTY
+
+  # Abstract class for type coercions
+  #
+  # @abstract
+  class Coercer
+    include TTY::Equatable
+
+  end # Coercer
+
+end # TTY

data/lib/tty/coercer/boolean.rb

@@ -0,0 +1,39 @@
+# -*- encoding: utf-8 -*-
+
+module TTY
+  class Coercer
+
+    # A class responsible for boolean type coercion
+    class Boolean
+
+      # Coerce value to boolean type including range of strings such as
+      #
+      # @param [Object] value
+      #
+      # @example
+      #   coerce("True") # => true
+      #
+      #   other values coerced to true are:
+      #     1, t, T, TRUE,  true,  True,  y, Y, YES, yes, Yes
+      #
+      #  coerce("False") # => false
+      #
+      #  other values coerced to false are:
+      #    0, f, F, FALSE, false, False, n, N, No,  no,  No
+      #
+      # @api public
+      def self.coerce(value)
+        case value.to_s
+        when %r/^(yes|y|t(rue)?|1)$/i
+          return true
+        when %r/^(no|n|f(alse)?|0)$/i
+          return false
+        else
+          raise TypeError, "Expected boolean type, got #{value}"
+        end
+      end
+
+    end # Boolean
+
+  end # Coercer
+end # TTY

data/lib/tty/coercer/float.rb

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+
+module TTY
+  class Coercer
+
+      class Float
+
+        def self.coerce(value, strict=true)
+          begin
+            Kernel.send(:Float, value.to_s)
+          rescue
+            if strict
+              raise InvalidArgument, "#{value} could not be coerced into Float"
+            else
+              value.to_f
+            end
+          end
+        end
+
+      end # Float
+
+  end # Coercer
+end # TTY

data/lib/tty/coercer/integer.rb

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+
+module TTY
+  class Coercer
+
+      class Integer
+
+        def self.coerce(value, strict=true)
+          begin
+            Kernel.send(:Integer, value.to_s)
+          rescue
+            if strict
+              raise InvalidArgument, "#{value} could not be coerced into Integer"
+            else
+              value.to_i
+            end
+          end
+        end
+
+      end # Integer
+
+  end # Coercer
+end # TTY

data/lib/tty/coercer/range.rb

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+
+module TTY
+  class Coercer
+
+    # A class responsible for range type coercion
+    class Range
+
+      # Coerce value to Range type with possible ranges
+      #
+      # @param [Object] value
+      #
+      # @example
+      #   coerce('0-9') # => (0..9)
+      #
+      # @api public
+      def self.coerce(value)
+        case value.to_s
+        when /\A(\-?\d+)\Z/
+          ::Range.new($1.to_i, $1.to_i)
+        when /\A(-?\d+?)(\.{2}\.?|-|,)(-?\d+)\Z/
+          ::Range.new($1.to_i, $3.to_i, $2 == '...')
+        when /\A(\w)(\.{2}\.?|-|,)(\w)\Z/
+          ::Range.new($1.to_s, $3.to_s, $2 == '...')
+        else
+          raise InvalidArgument, "#{value} could not be coerced into Range type"
+        end
+      end
+
+    end # Range
+
+  end # Coercer
+end # TTY

data/lib/tty/shell.rb

@@ -11,12 +11,16 @@ module TTY
     # @api private
     attr_reader :output
 
+    # @api private
+    attr_reader :prefix
+
     # Initialize a Shell
     #
     # @api public
-    def initialize(input=stdin, output=stdout)
+    def initialize(input=stdin, output=stdout, options={})
       @input  = input
       @output = output
+      @prefix = options.fetch(:prefix) { '' }
     end
 
     # Ask a question.
@@ -39,7 +43,7 @@ module TTY
     def ask(statement, *args, &block)
       options = Utils.extract_options!(args)
 
-      question = Question.new self, statement, options
+      question = Question.new self, options
       question.instance_eval(&block) if block_given?
       question.prompt(statement)
     end

data/lib/tty/shell/question.rb

@@ -1,21 +1,23 @@
 # -*- encoding: utf-8 -*-
 
+require 'date'
+
 module TTY
+  # A class responsible for shell prompt interactions.
   class Shell
 
     # A class representing a question.
     class Question
+      include TTY::Shell::ResponseDelegation
 
       PREFIX          = " + "
       MULTIPLE_PREFIX = "   * "
       ERROR_PREFIX    = "  ERROR:"
 
-      VALID_TYPES = [:boolean, :string, :symbol, :integer, :float, :date, :datetime]
-
-      # Store question.
+      # Store statement.
       #
       # @api private
-      attr_accessor :question
+      attr_accessor :statement
 
       # Store default value.
       #
@@ -27,40 +29,50 @@ module TTY
 
       attr_reader :validation
 
-      # Controls character processing to the answer
+      # Controls character processing of the answer
       #
       # @api public
       attr_reader :modifier
 
+      # Returns valid answers
+      #
+      # @api public
       attr_reader :valid_values
 
       attr_reader :error
 
-      attr_reader :statement
+      # Returns echo mode
+      #
+      # @api public
+      attr_reader :echo
 
-      # Expected answer type
+      # Returns character mask
       #
-      # @api private
-      attr_reader :type
+      # @api public
+      attr_reader :mask
+
+      # Returns character mode
+      #
+      # @api public
+      attr_reader :character
 
       # @api private
       attr_reader :shell
       private :shell
 
-      def initialize(shell, statement, options={})
-        @shell        = shell || Shell.new
-        @statement    = statement
-        @required     = options.fetch :required, false
-        @modifier     = Modifier.new options.fetch(:modifier, [])
-        @valid_values = options.fetch :valid, []
-        @validation   = Validation.new options.fetch(:validation, nil)
-      end
-
-      # Check if required argument present.
+      # Initialize a Question
       #
-      # @api private
-      def required?
-        required
+      # @api public
+      def initialize(shell, options={})
+        @shell        = shell || Shell.new
+        @required     = options.fetch(:required) { false }
+        @echo         = options.fetch(:echo) { true }
+        @mask         = options.fetch(:mask) { false  }
+        @character    = options.fetch(:character) { false }
+        @in           = options.fetch(:in) { false }
+        @modifier     = Modifier.new options.fetch(:modifier) { [] }
+        @valid_values = options.fetch(:valid) { [] }
+        @validation   = Validation.new options.fetch(:validation) { nil }
       end
 
       # Set a new prompt
@@ -70,8 +82,8 @@ module TTY
       # @return [self]
       #
       def prompt(message)
-        self.question = message
-        shell.say question
+        self.statement = message
+        shell.say shell.prefix + statement
         self
       end
 
@@ -84,6 +96,11 @@ module TTY
         self
       end
 
+      # Check if default value is set
+      #
+      # @return [Boolean]
+      #
+      # @api public
       def default?
         !!@default_value
       end
@@ -103,6 +120,15 @@ module TTY
         self
       end
 
+      # Check if required argument present.
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      def required?
+        required
+      end
+
       # Set validation rule for an argument
       #
       # @param [Object] value
@@ -115,26 +141,24 @@ module TTY
         self
       end
 
+      # Set expected values
+      #
+      # @param [Array] values
+      #
+      # @return [self]
+      #
       # @api public
-      def valid(value)
-        @valid_values = value
+      def valid(values)
+        @valid_values = values
         self
       end
 
-      # @api private
-      def check_valid(value)
-        if Array(value).all? { |val| @valid_values.include? val }
-          return value
-        else raise InvalidArgument, "Valid values are: #{@valid_values.join(', ')}"
-        end
-      end
 
       # Reset question object.
       #
       # @api public
       def clean
-        @question      = nil
-        @type          = nil
+        @statement     = nil
         @default_value = nil
         @required      = false
         @modifier      = nil
@@ -150,152 +174,148 @@ module TTY
         self
       end
 
+      # Setup behaviour when error(s) occur
+      #
       # @api public
       def on_error(action=nil)
         @error = action
         self
       end
 
-      # @api private
-      def read(type=nil)
-        result = shell.input.gets
-        if !result && default?
-          return default_value
-        end
-        if required? && !default? && !result
-          raise ArgumentRequired, 'No value provided for required'
-        end
-        validation.valid_value? result
-        modifier.apply_to result
-      end
-
-      # Read answer and cast to String type
-      #
-      # @param [String] error
-      #   error to display on failed conversion to string type
+      # Check if error behaviour is set
       #
       # @api public
-      def read_string(error=nil)
-        String(read)
+      def error?
+        !!@error
       end
 
-      # Read multiple line answer and cast to String type
-      def read_text
-        String(read)
-      end
-
-      # Read ansewr and cast to Symbol type
-      def read_symbol(error=nil)
-        read.to_sym
-      end
-
-      def read_int(error=nil)
-        Kernel.send(:Integer, read)
-      end
-
-      def read_float(error=nil)
-        Kernel.send(:Float, read)
-      end
-
-      def read_regex(error=nil)
-        Kernel.send(:Regex, read)
+      # Turn terminal echo on or off. This is used to secure the display so
+      # that the entered characters are not echoed back to the screen.
+      #
+      # @api public
+      def echo(value=(not_set=true))
+        return @echo if not_set
+        @echo = value
+        self
       end
 
-      def read_date
-        Date.parse(read)
+      # Chec if echo is set
+      #
+      # @api public
+      def echo?
+        !!@echo
       end
 
-      def read_datetime
-        DateTime.parse(read)
+      # Set character for masking the STDIN input
+      #
+      # @param [String] character
+      #
+      # @return [self]
+      #
+      # @api public
+      def mask(character=(not_set=true))
+        return @mask if not_set
+        @mask = character
+        self
       end
 
-      def read_bool(error=nil)
-        parse_boolean read
+      # Check if character mask is set
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def mask?
+        !!@mask
       end
 
-      def read_choice(type=nil)
-        @required = true unless default?
-        check_valid read
+      # Set if the input is character based or not
+      #
+      # @param [Boolean] value
+      #
+      # @return [self]
+      #
+      # @api public
+      def character(value=(not_set=true))
+        return @character if not_set
+        @character = value
+        self
       end
 
-      def read_file(error=nil)
-        File.open(File.join(directory, read))
+      # Check if character intput is set
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def character?
+        !!@character
       end
 
-      # Ignore exception
+      # Set expect range of values
       #
-      # @api private
-      def with_exception(&block)
-        yield
-      rescue
-        block.call
+      # @param [String] value
+      #
+      # @api public
+      def in(value=(not_set=true))
+        return @in if not_set
+        @in = TTY::Coercer::Range.coerce value
+        self
       end
 
-      # Reads string answer and validates against email regex
+      # Check if range is set
       #
-      # @return [String]
+      # @return [Boolean]
       #
       # @api public
-      def read_email
-        validate(/^[a-z0-9._%+-]+@([a-z0-9-]+\.)+[a-z]{2,6}$/i)
-        if error
-          self.prompt statement
-          with_exception { read_string }
-        else
-          read_string
-        end
+      def in?
+        !!@in
       end
 
-      # Read answer provided on multiple lines
+      # Check if response matches all the requirements set by the question
       #
-      # @api public
-      def read_multiple
-        response = ""
-        loop do
-          value = read
-          break if !value || value == ""
-          response << value
-        end
-        response
+      # @param [Object] value
+      #
+      # @return [Object]
+      #
+      # @api private
+      def evaluate_response(value)
+        return default_value if !value && default?
+
+        check_required value
+        check_valid    value unless valid_values.empty?
+        within?        value
+        validation.valid_value? value
+        modifier.apply_to value
       end
 
-      protected
+      private
 
-      # @param [Symbol] type
-      #   :boolean, :string, :numeric, :array
+      # Check if value is present
       #
       # @api private
-      def read_type(type)
-        raise TypeError, "Type #{type} is not valid" if type && !valid_type?(type)
-        case type
-        when :string
-          read_string
-        when :symbol
-          read_symbol
-        when :float
-          read_float
+      def check_required(value)
+        if required? && !default? && !value
+          raise ArgumentRequired, 'No value provided for required'
         end
       end
 
-      def valid_type?(type)
-        self.class::VALID_TYPES.include? type.to_sym
+      # Check if value matches any of the expected values
+      #
+      # @api private
+      def check_valid(value)
+        if Array(value).all? { |val| valid_values.include? val }
+          return value
+        else raise InvalidArgument, "Valid values are: #{valid_values.join(', ')}"
+        end
       end
 
-      # Convert message into boolean type
-      #
-      # @param [String] message
-      #
-      # @return [Boolean]
+      # Check if value is within expected range
       #
       # @api private
-      def parse_boolean(message)
-        case message.to_s
-        when %r/^(yes|y)$/i
-          return true
-        when %r/^(no|n)$/i
-          return false
-        else
-          raise TypeError, "Expected boolean type, got #{message}"
+      def within?(value)
+        if in? && value
+          if @in.include?(value)
+          else raise InvalidArgument, "Value #{value} is not included in the range #{@in}"
+          end
         end
       end