tty-prompt 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4ff94c2773632a84c5e652c8c725cdc576718ae6
-  data.tar.gz: 382b630ad1f975325744210cb7a308bfc09175e2
+  metadata.gz: 7c73bc3ac5978ca2ec1610fee367e6e04e66c0ec
+  data.tar.gz: 3350a73010eb30efd4494799ff5a6e8437115a42
 SHA512:
-  metadata.gz: ed722a06def652f9cb1e02fa627fe28ebfdfa0a8bdfa7a36e426b8976d4c0eab287f1e50f2800f2b7c87a185d1b4325d7628409991f6ba9061029976909c2805
-  data.tar.gz: 5bad4344ba8e132eaf35409329ab8583aa52f2a94a296b5b23eb13cb11c3436e71601c7bd9351ecf17d70b1851d910b2600e4ea8cfea81e08d3de507edbfa43f
+  metadata.gz: cd4716769f48d957e8ef5f4167a231d042126ab565267697b3541cd150629c669079275c1cdf66b7d3bba60b02d0b800458d3b84d1f0d0fa26c3c7cce202b709
+  data.tar.gz: 003c09c9afe7d9f3e3b6014bc5352150f49a1609827c637342605f34fcbbac59f0a913b6d20f68cad8b698387b720c00f3025ab3a1fa30984b226adaada07f1f

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Change log
 
+## [v0.12.0] - 2017-03-19
+
+### Added
+* Add Multiline question type
+* Add Keypress question type
+* Add Reader::History for storing buffered lines
+* Add Reader::Line for line abstraction
+
+### Changed
+* Remove :read option from Question
+* Chnage Reader#read_line to handle raw mode for processing special
+  characters such as Ctrl+x, navigate through history buffer
+  using up/down arrows, allow editing current line by moving left/right
+  with arrow keys and inserting content
+* Change Reader#read_multiline to gather multi line input correctly,
+  skip empty lines and terminate when Ctrl+d and Ctrl+z are pressed
+* Change Reader::Mode to check if tty is available by Matt Martyn (@MMartyn)
+* Change #keypress prompt to correctly refresh line and accept :keys & :timeout options
+
+### Fixed
+* Fix issue with #select, #multi_selct, #enum_select when choices are
+  provided as hash object together with prompt options.
+* Fix issue with default parameter for yes?/no? prompt by Carlos Fonseca (@carlosefonseca)
+* Fix List#help to allow setting help text through DSL
+
 ## [v0.11.0] - 2017-02-26
 
 ### Added

data/README.md

@@ -56,6 +56,7 @@ Or install it yourself as:
     * [2.1.7 required](#217-required)
     * [2.1.8 validate](#218-validate)
   * [2.2 keypress](#22-keypress)
+    * [2.2.1 timeout](#221-timeout)
   * [2.3 multiline](#23-multiline)
   * [2.4 mask](#24-mask)
   * [2.5 yes?/no?](#25-yesno)
@@ -79,6 +80,7 @@ Or install it yourself as:
   * [3.3 help_color](#33-help_color)
   * [3.4 interrupt](#34-interrupt)
   * [3.5 prefix](#35-prefix)
+  * [3.6 trakc_history](#36-track_history)
 
 ## 1. Usage
 
@@ -349,21 +351,61 @@ prompt.ask('What is your email?') { |q| q.validate :email }
 
 ### 2.2. keypress
 
-In order to ask question with a single character or keypress answer use `keypress`:
+In order to ask question that awaits a single character answer use `keypress` prompt like so:
 
 ```ruby
-prompt.keypress("Which one do you prefer a, b, c or d ?")
+prompt.keypress("Press key ?")
+# Press key?
+# => a
+```
+
+By default any key is accepted but you can limit keys by using `:keys` option. Any key event names such as `:space` or `:ctrl_k` are valid:
+
+```ruby
+prompt.keypress("Press space or enter to continue, keys: [:space, :return])
+```
+
+#### 2.2.1 timeout
+
+Timeout can be set using `:timeout` option to expire prompt and allow the script to continue automatically:
+
+```ruby
+prompt.keypress("Press any key to continue, resumes automatically in 3 seconds ...", timeout: 3)
+```
+
+In addition the `keypress` recognises `:countdown` token when inserted inside the question. It will automatically countdown the time in seconds:
+
+```ruby
+prompt.keypress("Press any key to continue, resumes automatically in :countdown ...", timeout: 3)
 ```
 
 ### 2.3 multiline
 
-Asking for multiline input can be done with `multiline` method.
+Asking for multiline input can be done with `multiline` method. The reading of input will terminate when `Ctrl+d` or `Ctrl+z` is pressed. Empty lines will not be included in the returned array.
 
 ```ruby
-prompt.multiline("Provide description?")
+prompt.multiline("Description?")
+# Description? (Press CTRL-D or CTRL-Z to finish)
+# I know not all that may be coming,
+# but be it what it will,
+# I'll go to it laughing.
+# => ["I know not all that may be coming,\n", "but be it what it will,\n", "I'll go to it laughing.\n"]
 ```
 
-The reading of input will terminate when empty line is submitted.
+The `multiline` uses similar options to those supported by `ask` prompt. For example, to provide default description:
+
+```ruby
+prompt.multiline("Description?", default: 'A super sweet prompt.')
+```
+
+or using DSL:
+
+```ruby
+prompt.multiline("Description?") do |q|
+  q.default 'A super sweet prompt.'
+  q.help 'Press thy ctrl+d to end'
+end
+```
 
 ### 2.4 mask
 
@@ -377,8 +419,9 @@ prompt.mask('What is your secret?')
 The masking character can be changed by passing `:mask` option:
 
 ```ruby
-prompt.mask('What is your secret?', mask: '\u2665')
-# => What is your secret? ♥♥♥♥♥
+heart = prompt.decorate('❤ ', :magenta)
+prompt.mask('What is your secret?', mask: heart)
+# => What is your secret? ❤  ❤  ❤  ❤  ❤ 
 ```
 
 If you don't wish to show any output use `:echo` option like so:
@@ -387,6 +430,14 @@ If you don't wish to show any output use `:echo` option like so:
 prompt.mask('What is your secret?', echo: false)
 ```
 
+You can also provide validation for your mask to enforce for instance strong passwords:
+
+```ruby
+prompt.mask('What is your secret?', mask: heart) do |q|
+  q.validate(/[a-z\ ]{5,15}/)
+end
+```
+
 ### 2.5 yes?/no?
 
 In order to display a query asking for boolean input from user use `yes?` like so:
@@ -1058,6 +1109,14 @@ You can prefix each question asked using the `:prefix` option. This option can b
 prompt = TTY::Prompt.new(prefix: '[?] ')
 ```
 
+### 3.6 track_history
+
+The prompts that accept line input such as `multiline` or `ask` provide history buffer that tracks all the lines entered during `TTY::Prompt.new` interactions. The history buffer provides previoius or next lines when user presses up/down arrows respectively. However, if you wish to disable this behaviour use `:track_history` option like so:
+
+```ruby
+prompt = TTY::Prompt.new(track_history: false)
+```
+
 ## Contributing
 
 1. Fork it ( https://github.com/piotrmurach/tty-prompt/fork )

data/examples/key_events.rb

@@ -0,0 +1,11 @@
+# encoding: utf-8
+
+require 'tty-prompt'
+
+prompt = TTY::Prompt::new(interrupt: :exit)
+
+prompt.on(:keypress) do |event|
+  puts "name: #{event.key.name}, value: #{event.value.dump}"
+end
+
+prompt.read_keypress

data/examples/keypress.rb

@@ -2,10 +2,8 @@
 
 require 'tty-prompt'
 
-prompt = TTY::Prompt::new(interrupt: :exit)
+prompt = TTY::Prompt::new
 
-prompt.on(:keypress) do |event|
-  puts "name: #{event.key.name}, value: #{event.value.dump}"
-end
+answer = prompt.keypress("Press any key to continue")
 
-prompt.read_keypress
+puts "Answer: #{answer}"

data/examples/multiline.rb

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+require 'tty-prompt'
+
+prompt = TTY::Prompt::new
+
+answer = prompt.multiline("Description:")
+
+puts "Answer: #{answer.inspect}"

data/examples/pause.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+
+require 'tty-prompt'
+
+prompt = TTY::Prompt::new
+
+prompt.keypress("Press space or enter to continue, continuing automatically in :countdown ...", keys: [:space, :return], timeout: 3)

data/lib/tty/prompt.rb

@@ -8,8 +8,10 @@ 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/reader'
@@ -87,6 +89,28 @@ module TTY
 
     # Initialize a Prompt
     #
+    # @param [Hash] options
+    # @option options [IO] :input
+    #   the input stream
+    # @option options [IO] :output
+    #   the output stream
+    # @option options [Hash] :env
+    #   the environment variables
+    # @option options [String] :prefix
+    #   the prompt prefix, by default empty
+    # @option options [Boolean] :enable_color
+    #   enable color support, true by default
+    # @option options [String] :active_color
+    #   the color used for selected option
+    # @option options [String] :help_color
+    #   the color used for help text
+    # @option options [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)
@@ -98,10 +122,29 @@ module TTY
       @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 }
 
       @cursor = TTY::Cursor
       @pastel = Pastel.new(@enabled_color.nil? ? {} : { enabled: @enabled_color })
-      @reader = Reader.new(@input, @output, interrupt: options[:interrupt], env: @env)
+      @reader = Reader.new(@input, @output, interrupt: @interrupt,
+                           track_history: @track_history, env: @env)
+    end
+
+    # Invoke a question type of prompt
+    #
+    # @example
+    #   prompt = TTY::Prompt.new
+    #   prompt.invoke_question(Question, "Your name? ")
+    #
+    # @return [String]
+    #
+    # @api public
+    def invoke_question(object, message, *args, &block)
+      options = Utils.extract_options!(args)
+      options[:messages] = self.class.messages
+      question = object.new(self, options)
+      question.(message, &block)
     end
 
     # Ask a question.
@@ -122,10 +165,7 @@ module TTY
     #
     # @api public
     def ask(message, *args, &block)
-      options = Utils.extract_options!(args)
-      options.merge!({messages: self.class.messages})
-      question = Question.new(self, options)
-      question.call(message, &block)
+      invoke_question(Question, message, *args, &block)
     end
 
     # Ask a question with a keypress answer
@@ -134,22 +174,47 @@ module TTY
     #
     # @api public
     def keypress(message, *args, &block)
-      options = Utils.extract_options!(args)
-      options.merge!(read: :keypress)
-      args << options
-      ask(message, *args, &block)
+      invoke_question(Keypress, message, *args, &block)
     end
 
     # Ask a question with a multiline answer
     #
-    # @see @ask
+    # @example
+    #   prompt.multiline('Description?')
+    #
+    # @return [Array[String]]
     #
     # @api public
     def multiline(message, *args, &block)
+      invoke_question(Multiline, message, *args, &block)
+    end
+
+    # Invoke a list type of prompt
+    #
+    # @example
+    #   prompt = TTY::Prompt.new
+    #   editors = %w(emacs nano vim)
+    #   prompt.invoke_select(EnumList, "Select editor: ", editors)
+    #
+    # @return [String]
+    #
+    # @api public
+    def invoke_select(object, question, *args, &block)
       options = Utils.extract_options!(args)
-      options.merge!(read: :multiline)
-      args << options
-      ask(message, *args, &block)
+      choices = if block
+                  []
+                elsif args.empty?
+                  possible = options.dup
+                  options = {}
+                  possible
+                elsif args.size == 1 && args[0].is_a?(Hash)
+                  Utils.extract_options!(args)
+                else
+                  args.flatten
+                end
+
+      list = object.new(self, options)
+      list.(question, choices, &block)
     end
 
     # Ask masked question
@@ -162,10 +227,7 @@ module TTY
     #
     # @api public
     def mask(message, *args, &block)
-      options = Utils.extract_options!(args)
-      options.merge!({messages: self.class.messages})
-      question = MaskQuestion.new(self, options)
-      question.call(message, &block)
+      invoke_question(MaskQuestion, message, *args, &block)
     end
 
     # Ask a question with a list of options
@@ -232,30 +294,6 @@ module TTY
       invoke_select(EnumList, question, *args, &block)
     end
 
-    # Invoke a list type of prompt
-    #
-    # @example
-    #   prompt = TTY::Prompt.new
-    #   editors = %w(emacs nano vim)
-    #   prompt.invoke_select(EnumList, "Select editor: ", editors)
-    #
-    # @return [String]
-    #
-    # @api public
-    def invoke_select(object, question, *args, &block)
-      options = Utils.extract_options!(args)
-      choices = if block
-                  []
-                elsif args.empty?
-                  options
-                else
-                  args.flatten
-                end
-
-      list = object.new(self, options)
-      list.call(question, choices, &block)
-    end
-
     # A shortcut method to ask the user positive question and return
     # true for 'yes' reply, false for 'no'.
     #
@@ -288,7 +326,7 @@ module TTY
     #
     # @api public
     def no?(message, *args, &block)
-      defaults = { default: false, type: :no }
+      defaults = { default: false }
       options  = Utils.extract_options!(args)
       options.merge!(defaults.reject { |k, _| options.key?(k) })
 
@@ -350,7 +388,7 @@ module TTY
     # @api public
     def say(message = '', options = {})
       message = message.to_s
-      return unless message.length > 0
+      return if message.empty?
 
       statement = Statement.new(self, options)
       statement.call(message)
@@ -491,7 +529,7 @@ module TTY
         enabled_color: enabled_color,
         help_color: help_color
       }
-      "#<#{self.class}: #{attributes.each { |name, val| "@#{name}=#{val}" } }"
+      "#<#{self.class}: #{attributes.each { |name, val| "@#{name}=#{val}" }}"
     end
   end # Prompt
 end # TTY

data/lib/tty/prompt/confirm_question.rb

@@ -16,11 +16,9 @@ module TTY
       # @api public
       def initialize(prompt, options = {})
         super
-
         @suffix   = options.fetch(:suffix)   { UndefinedSetting }
         @positive = options.fetch(:positive) { UndefinedSetting }
         @negative = options.fetch(:negative) { UndefinedSetting }
-        @type     = options.fetch(:type)     { :yes }
       end
 
       def positive?
@@ -38,21 +36,24 @@ module TTY
       # Set question suffix
       #
       # @api public
-      def suffix(value)
+      def suffix(value = (not_set = true))
+        return @negative if not_set
         @suffix = value
       end
 
       # Set value for matching positive choice
       #
       # @api public
-      def positive(value)
+      def positive(value = (not_set = true))
+        return @positive if not_set
         @positive = value
       end
 
       # Set value for matching negative choice
       #
       # @api public
-      def negative(value)
+      def negative(value = (not_set = true))
+        return @negative if not_set
         @negative = value
       end
 
@@ -66,10 +67,11 @@ module TTY
 
       # Render confirmation question
       #
+      # @return [String]
+      #
       # @api private
       def render_question
         header = "#{@prefix}#{message} "
-
         if !@done
           header += @prompt.decorate("(#{@suffix})", @help_color) + ' '
         else
@@ -77,24 +79,17 @@ module TTY
           label  = answer ? @positive : @negative
           header += @prompt.decorate(label, @active_color)
         end
-        @prompt.print(header)
-        @prompt.puts if @done
-
-        header.lines.count + (@done ? 1 : 0)
+        header << "\n" if @done
+        header
       end
 
       protected
 
-      # @api private
-      def is?(type)
-        @type == type
-      end
-
       # @api private
       def setup_defaults
         return if suffix? && positive?
 
-        if suffix? && !positive?
+        if suffix? && (!positive? || !negative?)
           parts = @suffix.split('/')
           @positive = parts[0]
           @negative = parts[1]
@@ -104,41 +99,30 @@ module TTY
           @convert = conversion
         else
           create_default_labels
-          @convert  = :bool
+          @convert = :bool
         end
       end
 
+      # @api private
       def create_default_labels
-        if is?(:yes)
-          @suffix   = default? ? 'Y/n' : 'y/N'
-          @positive = default? ? 'Yes' : 'yes'
-          @negative = default? ? 'no' : 'No'
-        else
-          @suffix   = default? ? 'y/N' : 'Y/n'
-          @positive = default? ? 'Yes' : 'yes'
-          @negative = default? ? 'No'  : 'no'
-        end
+        @suffix   = default ? 'Y/n' : 'y/N'
+        @positive = default ? 'Yes' : 'yes'
+        @negative = default ? 'no' : 'No'
       end
 
       # @api private
       def create_suffix
         result = ''
-        if is?(:yes)
-          result << "#{default? ? @positive.capitalize : @positive.downcase}"
-          result << '/'
-          result << "#{default? ? @negative.downcase : @negative.capitalize}"
-        else
-          result << "#{default? ? @positive.downcase : @positive.capitalize}"
-          result << '/'
-          result << "#{default? ? @negative.capitalize : @negative.downcase}"
-        end
+        result << "#{default ? positive.capitalize : positive.downcase}"
+        result << '/'
+        result << "#{default ? negative.downcase : negative.capitalize}"
       end
 
       # Create custom conversion
       #
       # @api private
       def conversion
-        proc { |input| !input.match(/^#{@positive}|#{@positive[0]}$/i).nil? }
+        proc { |input| !input.match(/^#{positive}|#{positive[0]}$/i).nil? }
       end
     end # ConfirmQuestion
   end # Prompt