tty 0.0.5 → 0.0.6

data/README.md

@@ -4,18 +4,20 @@
 [travis]: http://travis-ci.org/peter-murach/tty
 [codeclimate]: https://codeclimate.com/github/peter-murach/tty
 
-Toolbox for developing CLI clients in Ruby.
+Toolbox for developing CLI clients in Ruby. This library provides a fluid interface for working with terminals.
 
 ## Features
 
 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: TODO)
+* Terminal output colorization.          (status: DONE)
 * Terminal & System detection utilities. (status: In Progress)
-* Text alignment/padding and diffs. (status: TODO)
-* Shell user interface. (status: TODO)
-* Progress bar. (status: TODO)
+* 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)
 * Fully tested with major ruby interpreters.
 * No dependencies to allow for easy gem vendoring.
 
@@ -113,10 +115,63 @@ To print border around data table you need to specify `renderer` type out of `ba
   term.color?   # => true or false
 ```
 
+To colorize your output do
+
+```ruby
+  term.color.set 'text...', :bold, :red, :on_green    # => red bold text on green background
+  term.color.remove 'text...'       # strips off ansi escape sequences
+  term.color.code :red              # ansi escape code for the supplied color
+```
+
 ### Shell
 
 Main responsibility is to interact with the prompt and provide convenience methods.
 
+In order to ask question and parse answers:
+
+```ruby
+  shell  = TTY::Shell.new
+  answer = shell.ask("What is your name?").read_string
+```
+
+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
+  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
+
+```ruby
+  shell.ask("What is your name?").argument(:required).default('Piotr').validate(/\w+\s\w+/).read_string
+
+  shell.ask "What is your name?" do
+    argument :required
+    default  'Piotr'
+    validate /\w+\s\w+/
+    valid    ['Piotr', 'Piotrek']
+    modify   :capitalize
+  end.read_string
+```
+
+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
+```
+
 ### System
 
 ```ruby

data/lib/tty/shell/question/modifier.rb

@@ -0,0 +1,96 @@
+# -*- encoding: utf-8 -*-
+
+module TTY
+  class Shell
+    class Question
+
+      # A class representing String modifications.
+      class Modifier
+
+        attr_reader :modifiers
+        private :modifiers
+
+        # Initialize a Modifier
+        #
+        # @api public
+        def initialize(*modifiers)
+          @modifiers = Array(modifiers)
+        end
+
+        # Change supplied value according to the given string transformation.
+        # Valid settings are:
+        #
+        # @param [String] value
+        #   the string to be modified
+        #
+        # @return [String]
+        #
+        # @api private
+        def apply_to(value)
+          modifiers.inject(value) do |result, mod|
+            result = Modifier.letter_case mod, result
+            result = Modifier.whitespace mod, result
+          end
+        end
+
+        # Changes letter casing in a string according to valid modifications.
+        # For invalid modification option the string is preserved.
+        #
+        # @param [Symbol] mod
+        #  the modification to change the string
+        #
+        # @option mod [Symbol] :up        change to upper case
+        # @option mod [Symbol] :upcase    change to upper case
+        # @option mod [Symbol] :uppercase change to upper case
+        # @option mod [Symbol] :down      change to lower case
+        # @option mod [Symbol] :downcase  change to lower case
+        # @option mod [Symbol] :capitalize change all words to start with uppercase case letter
+        #
+        # @return [String]
+        #
+        # @api public
+        def self.letter_case(mod, value)
+          case mod
+          when :up, :upcase, :uppercase
+            value.upcase
+          when :down, :downcase, :lowercase
+            value.downcase
+          when :capitalize
+            value.capitalize
+          else
+            value
+          end
+        end
+
+        # Changes whitespace in a string according to valid modifications.
+        #
+        # @param [Symbol] mod
+        #   the modification to change the string
+        #
+        # @option mod [String] :trim, :strip
+        #   remove whitespace for the start and end
+        # @option mod [String] :chomp     remove record separator from the end
+        # @option mod [String] :collapse  remove any duplicate whitespace
+        # @option mod [String] :remove    remove all whitespace
+        #
+        # @api public
+        def self.whitespace(mod, value)
+          case mod
+          when :trim, :strip
+            value.strip
+          when :chomp
+            value.chomp
+          when :collapse
+            value.gsub(/\s+/, ' ')
+          when :remove
+            value.gsub(/\s+/, '')
+          else
+            value
+          end
+        end
+
+      end # Modifier
+
+    end # Question
+  end # Shell
+end # TTY

data/lib/tty/shell/question/validation.rb

@@ -0,0 +1,91 @@
+# -*- encoding: utf-8 -*-
+
+module TTY
+  class Shell
+    class Question
+
+      # A class representing question validation.
+      class Validation
+
+        # @api private
+        attr_reader :validation
+        private :validation
+
+        # Initialize a Validation
+        #
+        # @param [Object] validation
+        #
+        # @return [undefined]
+        #
+        # @api private
+        def initialize(validation=nil)
+          @validation = validation ? coerce(validation) : validation
+        end
+
+        # Convert validation into known type.
+        #
+        # @param [Object] validation
+        #
+        # @raise [TTY::ValidationCoercion] failed to convert validation
+        #
+        # @api private
+        def coerce(validation)
+          case validation
+          when Proc
+            validation
+          when Regexp, String
+            Regexp.new(validation.to_s)
+          else
+            raise TTY::ValidationCoercion, "Wrong type, got #{validation.class}"
+          end
+        end
+
+        # Check if validation is required
+        #
+        # @return [Boolean]
+        #
+        # @api public
+        def validate?
+          !!validation
+        end
+
+        # Test if the value matches the validation
+        #
+        # @example
+        #   validation.valid_value?(value) # => true or false
+        #
+        # @param [Object] value
+        #  the value to validate
+        #
+        # @return [undefined]
+        #
+        # @api public
+        def valid_value?(value)
+          check_validation(value)
+        end
+
+        private
+
+        # Check if provided value passes validation
+        #
+        # @param [String] value
+        #
+        # @raise [TTY::InvalidArgument] unkown type of argument
+        #
+        # @return [undefined]
+        #
+        # @api private
+        def check_validation(value)
+          if validate? && value
+            value = value.to_s
+            if validation.is_a?(Regexp) && validation =~ value
+            elsif validation.is_a?(Proc) && validation.call(value)
+            else raise TTY::InvalidArgument, "Invalid input for #{value}"
+            end
+          end
+        end
+
+      end # Validation
+    end # Question
+  end # Shell
+end # TTY

data/lib/tty/shell/question.rb

@@ -0,0 +1,304 @@
+# -*- encoding: utf-8 -*-
+
+module TTY
+  class Shell
+
+    # A class representing a question.
+    class Question
+
+      PREFIX          = " + "
+      MULTIPLE_PREFIX = "   * "
+      ERROR_PREFIX    = "  ERROR:"
+
+      VALID_TYPES = [:boolean, :string, :symbol, :integer, :float, :date, :datetime]
+
+      # Store question.
+      #
+      # @api private
+      attr_accessor :question
+
+      # Store default value.
+      #
+      # @api private
+      attr_reader :default_value
+
+      attr_reader :required
+      private :required
+
+      attr_reader :validation
+
+      # Controls character processing to the answer
+      #
+      # @api public
+      attr_reader :modifier
+
+      attr_reader :valid_values
+
+      attr_reader :error
+
+      attr_reader :statement
+
+      # Expected answer type
+      #
+      # @api private
+      attr_reader :type
+
+      # @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.
+      #
+      # @api private
+      def required?
+        required
+      end
+
+      # Set a new prompt
+      #
+      # @param [String] message
+      #
+      # @return [self]
+      #
+      def prompt(message)
+        self.question = message
+        shell.say question
+        self
+      end
+
+      # Set default value.
+      #
+      # @api public
+      def default(value)
+        return self if value == ""
+        @default_value = value
+        self
+      end
+
+      def default?
+        !!@default_value
+      end
+
+      # Ensure that passed argument is present if required option
+      #
+      # @return [Question]
+      #
+      # @api public
+      def argument(value)
+        case value
+        when :required
+          @required = true
+        when :optional
+          @required = false
+        end
+        self
+      end
+
+      # Set validation rule for an argument
+      #
+      # @param [Object] value
+      #
+      # @return [Question]
+      #
+      # @api public
+      def validate(value=nil, &block)
+        @validation = Validation.new(value || block)
+        self
+      end
+
+      # @api public
+      def valid(value)
+        @valid_values = value
+        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
+        @default_value = nil
+        @required      = false
+        @modifier      = nil
+      end
+
+      # Modify string according to the rule given.
+      #
+      # @param [Symbol] rule
+      #
+      # @api public
+      def modify(*rules)
+        @modifier = Modifier.new *rules
+        self
+      end
+
+      # @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
+      #
+      # @api public
+      def read_string(error=nil)
+        String(read)
+      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)
+      end
+
+      def read_date
+        Date.parse(read)
+      end
+
+      def read_datetime
+        DateTime.parse(read)
+      end
+
+      def read_bool(error=nil)
+        parse_boolean read
+      end
+
+      def read_choice(type=nil)
+        @required = true unless default?
+        check_valid read
+      end
+
+      def read_file(error=nil)
+        File.open(File.join(directory, read))
+      end
+
+      # Ignore exception
+      #
+      # @api private
+      def with_exception(&block)
+        yield
+      rescue
+        block.call
+      end
+
+      # Reads string answer and validates against email regex
+      #
+      # @return [String]
+      #
+      # @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
+      end
+
+      # Read answer provided on multiple lines
+      #
+      # @api public
+      def read_multiple
+        response = ""
+        loop do
+          value = read
+          break if !value || value == ""
+          response << value
+        end
+        response
+      end
+
+      protected
+
+      # @param [Symbol] type
+      #   :boolean, :string, :numeric, :array
+      #
+      # @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
+        end
+      end
+
+      def valid_type?(type)
+        self.class::VALID_TYPES.include? type.to_sym
+      end
+
+      # Convert message into boolean type
+      #
+      # @param [String] message
+      #
+      # @return [Boolean]
+      #
+      # @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}"
+        end
+      end
+
+    end # Question
+  end # Shell
+end # TTY

data/lib/tty/shell/statement.rb

@@ -0,0 +1,55 @@
+# -*- encoding: utf-8 -*-
+
+module TTY
+  class Shell
+
+    # A class representing a statement output to shell.
+    class Statement
+
+      # @api private
+      attr_reader :shell
+      private :shell
+
+      attr_reader :newline
+
+      attr_reader :color
+
+      # Initialize a Statement
+      #
+      # @param [TTY::Shell] shell
+      #
+      # @param [Hash] options
+      #
+      # @option options [Symbol] :newline
+      #   force a newline break after the message
+      #
+      # @option options [Symbol] :color
+      #   change the message display to color
+      #
+      # @api public
+      def initialize(shell=nil, options={})
+        @shell = shell || Shell.new
+        @newline = options.fetch :newline, true
+        @color   = options.fetch :color, nil
+      end
+
+      # Output the message to the shell
+      #
+      # @param [String] message
+      #   the message to be printed to stdout
+      #
+      # @api public
+      def declare(message)
+        message = TTY::terminal.color.set message, *color if color
+
+        if newline && /( |\t)(\e\[\d+(;\d+)*m)?\Z/ !~ message
+          shell.output.puts message
+        else
+          shell.output.print message
+          shell.output.flush
+        end
+      end
+
+    end # Statement
+  end # Shell
+end # TTY