tty-prompt 0.18.0 → 0.22.0

data/lib/tty-prompt.rb

@@ -1,2 +1 @@
-require_relative 'tty/prompt'
-require_relative 'tty/test_prompt'
+require_relative "tty/prompt"

data/lib/tty/prompt.rb

@@ -1,49 +1,34 @@
 # frozen_string_literal: true
 
-require 'forwardable'
-require 'pastel'
-require 'tty-cursor'
-require 'tty-reader'
-
-require_relative 'prompt/answers_collector'
-require_relative 'prompt/confirm_question'
-require_relative 'prompt/expander'
-require_relative 'prompt/enum_list'
-require_relative 'prompt/keypress'
-require_relative 'prompt/list'
-require_relative 'prompt/multi_list'
-require_relative 'prompt/multiline'
-require_relative 'prompt/mask_question'
-require_relative 'prompt/question'
-require_relative 'prompt/slider'
-require_relative 'prompt/statement'
-require_relative 'prompt/suggestion'
-require_relative 'prompt/utils'
-require_relative 'prompt/version'
+require "forwardable"
+require "pastel"
+require "tty-cursor"
+require "tty-reader"
+require "tty-screen"
+
+require_relative "prompt/answers_collector"
+require_relative "prompt/confirm_question"
+require_relative "prompt/errors"
+require_relative "prompt/expander"
+require_relative "prompt/enum_list"
+require_relative "prompt/keypress"
+require_relative "prompt/list"
+require_relative "prompt/multi_list"
+require_relative "prompt/multiline"
+require_relative "prompt/mask_question"
+require_relative "prompt/question"
+require_relative "prompt/slider"
+require_relative "prompt/statement"
+require_relative "prompt/suggestion"
+require_relative "prompt/symbols"
+require_relative "prompt/utils"
+require_relative "prompt/version"
 
 module TTY
   # A main entry for asking prompt questions.
   class Prompt
     extend Forwardable
 
-    # Raised when wrong parameter is used to configure prompt
-    ConfigurationError = Class.new(StandardError)
-
-    # Raised when type conversion cannot be performed
-    ConversionError = Class.new(StandardError)
-
-    # Raised when the passed in validation argument is of wrong type
-    ValidationCoercion = Class.new(TypeError)
-
-    # Raised when the required argument is not supplied
-    ArgumentRequired = Class.new(ArgumentError)
-
-    # Raised when the argument validation fails
-    ArgumentValidation = Class.new(ArgumentError)
-
-    # Raised when the argument is not expected
-    InvalidArgument = Class.new(ArgumentError)
-
     # @api private
     attr_reader :input
 
@@ -69,12 +54,27 @@ module TTY
     # @api private
     attr_reader :active_color, :help_color, :error_color, :enabled_color
 
-    def_delegators :@pastel, :decorate, :strip
+    # Quiet mode
+    #
+    # @api private
+    attr_reader :quiet
+
+    # The collection of display symbols
+    #
+    # @example
+    #   prompt = TTY::Prompt.new(symbols: {marker: ">"})
+    #
+    # @return [Hash]
+    #
+    # @api private
+    attr_reader :symbols
+
+    def_delegators :@pastel, :strip
 
     def_delegators :@cursor, :clear_lines, :clear_line,
                    :show, :hide
 
-    def_delegators :@reader, :read_char, :read_line, :read_keypress,
+    def_delegators :@reader, :read_char, :read_keypress, :read_line,
                    :read_multiline, :on, :subscribe, :unsubscribe, :trigger,
                    :count_screen_lines
 
@@ -82,61 +82,90 @@ module TTY
 
     def self.messages
       {
-        range?: 'Value %{value} must be within the range %{in}',
-        valid?: 'Your answer is invalid (must match %{valid})',
-        required?: 'Value must be provided'
+        range?: "Value %{value} must be within the range %{in}",
+        valid?: "Your answer is invalid (must match %{valid})",
+        required?: "Value must be provided",
+        convert?: "Cannot convert `%{value}` to '%{type}' type"
       }
     end
 
     # Initialize a Prompt
     #
-    # @param [Hash] options
-    # @option options [IO] :input
+    # @param [IO] :input
     #   the input stream
-    # @option options [IO] :output
+    # @param [IO] :output
     #   the output stream
-    # @option options [Hash] :env
+    # @param [Hash] :env
     #   the environment variables
-    # @option options [String] :prefix
+    # @param [Hash] :symbols
+    #   the symbols displayed in prompts such as :marker, :cross
+    # @param options [Boolean] :quiet
+    #   enable quiet mode, don't re-echo the question
+    # @param [String] :prefix
     #   the prompt prefix, by default empty
-    # @option options [Boolean] :enable_color
+    # @param [Symbol] :interrupt
+    #   handling of Ctrl+C key out of :signal, :exit, :noop
+    # @param [Boolean] :track_history
+    #   disable line history tracking, true by default
+    # @param [Boolean] :enable_color
     #   enable color support, true by default
-    # @option options [String] :active_color
+    # @param [String,Proc] :active_color
     #   the color used for selected option
-    # @option options [String] :help_color
+    # @param [String,Proc] :help_color
     #   the color used for help text
-    # @option options [String] :error_color
+    # @param [String] :error_color
     #   the color used for displaying error messages
-    # @option options [Symbol] :interrupt
-    #   handling of Ctrl+C key out of :signal, :exit, :noop
-    # @option options [Boolean] :track_history
-    #   disable line history tracking, true by default
     #
     # @api public
-    def initialize(*args)
-      options = Utils.extract_options!(args)
-      @input  = options.fetch(:input) { $stdin }
-      @output = options.fetch(:output) { $stdout }
-      @env    = options.fetch(:env) { ENV }
-      @prefix = options.fetch(:prefix) { '' }
-      @enabled_color = options[:enable_color]
-      @active_color  = options.fetch(:active_color) { :green }
-      @help_color    = options.fetch(:help_color)   { :bright_black }
-      @error_color   = options.fetch(:error_color)  { :red }
-      @interrupt     = options.fetch(:interrupt)    { :error }
-      @track_history = options.fetch(:track_history) { true }
+    def initialize(input: $stdin, output: $stdout, env: ENV, symbols: {},
+                   prefix: "", interrupt: :error, track_history: true,
+                   quiet: false, enable_color: nil, active_color: :green,
+                   help_color: :bright_black, error_color: :red)
+      @input  = input
+      @output = output
+      @env    = env
+      @prefix = prefix
+      @enabled_color = enable_color
+      @active_color  = active_color
+      @help_color    = help_color
+      @error_color   = error_color
+      @interrupt     = interrupt
+      @track_history = track_history
+      @symbols       = Symbols.symbols.merge(symbols)
+      @quiet         = quiet
 
       @cursor = TTY::Cursor
-      @pastel = Pastel.new(@enabled_color.nil? ? {} : { enabled: @enabled_color })
+      @pastel = enabled_color.nil? ? Pastel.new : Pastel.new(enabled: enabled_color)
       @reader = TTY::Reader.new(
-        input: @input,
-        output: @output,
-        interrupt: @interrupt,
-        track_history: @track_history,
-        env: @env
+        input: input,
+        output: output,
+        interrupt: interrupt,
+        track_history: track_history,
+        env: env
       )
     end
 
+    # Decorate a string with colors
+    #
+    # @param [String] :string
+    #   the string to color
+    # @param [Array<Proc|Symbol>] :colors
+    #   collection of color symbols or callable object
+    #
+    # @api public
+    def decorate(string, *colors)
+      if Utils.blank?(string) || @enabled_color == false || colors.empty?
+        return string
+      end
+
+      coloring = colors.first
+      if coloring.respond_to?(:call)
+        coloring.call(string)
+      else
+        @pastel.decorate(string, *colors)
+      end
+    end
+
     # Invoke a question type of prompt
     #
     # @example
@@ -146,10 +175,9 @@ module TTY
     # @return [String]
     #
     # @api public
-    def invoke_question(object, message, *args, &block)
-      options = Utils.extract_options!(args)
+    def invoke_question(object, message, **options, &block)
       options[:messages] = self.class.messages
-      question = object.new(self, options)
+      question = object.new(self, **options)
       question.(message, &block)
     end
 
@@ -170,8 +198,8 @@ module TTY
     # @return [TTY::Prompt::Question]
     #
     # @api public
-    def ask(message, *args, &block)
-      invoke_question(Question, message, *args, &block)
+    def ask(message = "", **options, &block)
+      invoke_question(Question, message, **options, &block)
     end
 
     # Ask a question with a keypress answer
@@ -179,20 +207,20 @@ module TTY
     # @see #ask
     #
     # @api public
-    def keypress(message, *args, &block)
-      invoke_question(Keypress, message, *args, &block)
+    def keypress(message = "", **options, &block)
+      invoke_question(Keypress, message, **options, &block)
     end
 
     # Ask a question with a multiline answer
     #
     # @example
-    #   prompt.multiline('Description?')
+    #   prompt.multiline("Description?")
     #
     # @return [Array[String]]
     #
     # @api public
-    def multiline(message, *args, &block)
-      invoke_question(Multiline, message, *args, &block)
+    def multiline(message = "", **options, &block)
+      invoke_question(Multiline, message, **options, &block)
     end
 
     # Invoke a list type of prompt
@@ -207,9 +235,7 @@ module TTY
     # @api public
     def invoke_select(object, question, *args, &block)
       options = Utils.extract_options!(args)
-      choices = if block
-                  []
-                elsif args.empty?
+      choices = if args.empty? && !block
                   possible = options.dup
                   options = {}
                   possible
@@ -219,7 +245,7 @@ module TTY
                   args.flatten
                 end
 
-      list = object.new(self, options)
+      list = object.new(self, **options)
       list.(question, choices, &block)
     end
 
@@ -232,8 +258,8 @@ module TTY
     # @return [TTY::Prompt::MaskQuestion]
     #
     # @api public
-    def mask(message, *args, &block)
-      invoke_question(MaskQuestion, message, *args, &block)
+    def mask(message = "", **options, &block)
+      invoke_question(MaskQuestion, message, **options, &block)
     end
 
     # Ask a question with a list of options
@@ -301,42 +327,36 @@ module TTY
     end
 
     # A shortcut method to ask the user positive question and return
-    # true for 'yes' reply, false for 'no'.
+    # true for "yes" reply, false for "no".
     #
     # @example
     #   prompt = TTY::Prompt.new
-    #   prompt.yes?('Are you human?')
+    #   prompt.yes?("Are you human?")
     #   # => Are you human? (Y/n)
     #
     # @return [Boolean]
     #
     # @api public
-    def yes?(message, *args, &block)
-      defaults = { default: true }
-      options  = Utils.extract_options!(args)
-      options.merge!(defaults.reject { |k, _| options.key?(k) })
-
-      question = ConfirmQuestion.new(self, options)
+    def yes?(message, **options, &block)
+      opts = { default: true }.merge(options)
+      question = ConfirmQuestion.new(self, **opts)
       question.call(message, &block)
     end
 
     # A shortcut method to ask the user negative question and return
-    # true for 'no' reply.
+    # true for "no" reply.
     #
     # @example
     #   prompt = TTY::Prompt.new
-    #   prompt.no?('Are you alien?') # => true
+    #   prompt.no?("Are you alien?") # => true
     #   # => Are you human? (y/N)
     #
     # @return [Boolean]
     #
     # @api public
-    def no?(message, *args, &block)
-      defaults = { default: false }
-      options  = Utils.extract_options!(args)
-      options.merge!(defaults.reject { |k, _| options.key?(k) })
-
-      question = ConfirmQuestion.new(self, options)
+    def no?(message, **options, &block)
+      opts = { default: false }.merge(options)
+      question = ConfirmQuestion.new(self, **opts)
       !question.call(message, &block)
     end
 
@@ -345,15 +365,15 @@ module TTY
     # @example
     #   prompt = TTY::Prompt.new
     #   choices = [{
-    #     key: 'Y',
-    #     name: 'Overwrite',
+    #     key: "Y",
+    #     name: "Overwrite",
     #     value: :yes
     #   }, {
-    #     key: 'n',
-    #     name: 'Skip',
+    #     key: "n",
+    #     name: "Skip",
     #     value: :no
     #   }]
-    #   prompt.expand('Overwirte Gemfile?', choices)
+    #   prompt.expand("Overwirte Gemfile?", choices)
     #
     # @return [Object]
     #   the user specified value
@@ -367,7 +387,7 @@ module TTY
     #
     # @example
     #   prompt = TTY::Prompt.new
-    #   prompt.slider('What size?', min: 32, max: 54, step: 2)
+    #   prompt.slider("What size?", min: 32, max: 54, step: 2)
     #
     # @param [String] question
     #   the question to ask
@@ -375,9 +395,8 @@ module TTY
     # @return [String]
     #
     # @api public
-    def slider(question, *args, &block)
-      options = Utils.extract_options!(args)
-      slider = Slider.new(self, options)
+    def slider(question, **options, &block)
+      slider = Slider.new(self, **options)
       slider.call(question, &block)
     end
 
@@ -392,11 +411,11 @@ module TTY
     # @return [String]
     #
     # @api public
-    def say(message = '', options = {})
+    def say(message = "", **options)
       message = message.to_s
       return if message.empty?
 
-      statement = Statement.new(self, options)
+      statement = Statement.new(self, **options)
       statement.call(message)
     end
 
@@ -411,9 +430,9 @@ module TTY
     # @return [Array] messages
     #
     # @api public
-    def ok(*args)
-      options = Utils.extract_options!(args)
-      args.each { |message| say message, options.merge(color: :green) }
+    def ok(*args, **options)
+      opts = { color: :green }.merge(options)
+      args.each { |message| say(message, **opts) }
     end
 
     # Print statement(s) out in yellow color.
@@ -427,9 +446,9 @@ module TTY
     # @return [Array] messages
     #
     # @api public
-    def warn(*args)
-      options = Utils.extract_options!(args)
-      args.each { |message| say message, options.merge(color: :yellow) }
+    def warn(*args, **options)
+      opts = { color: :yellow }.merge(options)
+      args.each { |message| say(message, **opts) }
     end
 
     # Print statement(s) out in red color.
@@ -443,16 +462,38 @@ module TTY
     # @return [Array] messages
     #
     # @api public
-    def error(*args)
-      options = Utils.extract_options!(args)
-      args.each { |message| say message, options.merge(color: :red) }
+    def error(*args, **options)
+      opts = { color: :red }.merge(options)
+      args.each { |message| say(message, **opts) }
+    end
+
+    # Print debug information in terminal top right corner
+    #
+    # @example
+    #   prompt.debug "info1", "info2"
+    #
+    # @param [Array] messages
+    #
+    # @retrun [nil]
+    #
+    # @api public
+    def debug(*messages)
+      longest = messages.max_by(&:length).size
+      width = TTY::Screen.width - longest
+      print cursor.save
+      messages.reverse_each do |msg|
+        print cursor.column(width) + cursor.up + cursor.clear_line_after
+        print msg
+      end
+    ensure
+      print cursor.restore
     end
 
     # Takes the string provided by the user and compare it with other possible
     # matches to suggest an unambigous string
     #
     # @example
-    #   prompt.suggest('sta', ['status', 'stage', 'commit', 'branch'])
+    #   prompt.suggest("sta", ["status", "stage", "commit", "branch"])
     #   # => "status, stage"
     #
     # @param [String] message
@@ -470,8 +511,8 @@ module TTY
     # @return [String]
     #
     # @api public
-    def suggest(message, possibilities, options = {})
-      suggestion = Suggestion.new(options)
+    def suggest(message, possibilities, **options)
+      suggestion = Suggestion.new(**options)
       say(suggestion.suggest(message, possibilities))
     end
 
@@ -479,15 +520,15 @@ module TTY
     #
     # @example
     #   prompt.collect do
-    #     key(:name).ask('Name?')
+    #     key(:name).ask("Name?")
     #   end
     #
     # @return [Hash]
     #   the collection of answers
     #
     # @api public
-    def collect(options = {}, &block)
-      collector = AnswersCollector.new(self, options)
+    def collect(**options, &block)
+      collector = AnswersCollector.new(self, **options)
       collector.call(&block)
     end
 
@@ -521,21 +562,24 @@ module TTY
       $stderr
     end
 
-    # Inspect class name and public attributes
+    # Inspect this instance public attributes
+    #
     # @return [String]
     #
     # @api public
     def inspect
-      attributes = {
-        input: input,
-        output: output,
-        prefix: prefix,
-        active_color: active_color,
-        error_color: error_color,
-        enabled_color: enabled_color,
-        help_color: help_color
-      }
-      "#<#{self.class}: #{attributes.each { |name, val| "@#{name}=#{val}" }}"
+      attributes = [
+        :prefix,
+        :quiet,
+        :enabled_color,
+        :active_color,
+        :error_color,
+        :help_color,
+        :input,
+        :output,
+      ]
+      name = self.class.name
+      "#<#{name}#{attributes.map { |attr| " #{attr}=#{send(attr).inspect}" }.join}>"
     end
   end # Prompt
 end # TTY