tty-prompt 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 74106ace23d50cc8593146b1b90c3b19ceca9914
-  data.tar.gz: d1719d051b15c93a321df9192315c8e4633b9e4d
+  metadata.gz: 5e24965d09c08a3bf136438bad66551d05f25a0f
+  data.tar.gz: 476702a67dd13fe4796c888d089107f4b6f7f18d
 SHA512:
-  metadata.gz: 6a5d268782541918e2f59b3e5c260c25fcd015e14004a1233ae69d5163ac8d76ffda6467ad29a2750efe561575639e355593403b426dd6fcbfb0aeda83fa4d77
-  data.tar.gz: df72ebf11ee221b0d9a49c9c4e8d6398afe161e4db3f48fed012aebf9f3a15dfe11caab3bb46def1837baddf864ff8d2291e522df4bb63ab49532ed1651f0f63
+  metadata.gz: 0645bb40ca7b847976e69d0d3c65e4e0a9441f4e3bade6ef1e0d38e7d9ef28e66132645aa30740c7a258939fe262664ed93306968eb76969bee768029d19c406
+  data.tar.gz: 70c03c2eb72010d0efe7d8a125c285dc32ec34117e29e2a44b17839c645a8b1650dd14d1184b7b8a871dc92b2c44121ab1e727aa9f5ca41c893184b678171fc8

data/.travis.yml

@@ -17,8 +17,6 @@ matrix:
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head
-    - rvm: jruby-20mode
-    - rvm: jruby-21mode
   fast_finish: true
 branches:
   only: master

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+0.2.0 (Nov 23, 2015)
+
+* Add ability to select choice form list #select
+* Add ability to select multiple options #multi_select
+* Change #ask api to be similar to #select and #multi_select behaviour
+* Change #ask :argument option to be :required
+* Add :read option to #ask for reading specific type input
+* Remove :valid option from #ask as #select is a better solution
+
+0.1.0 (Nov 1, 2015)
+
+* Initial implementation and release

data/README.md

@@ -17,8 +17,8 @@
 
 ## Features
 
+* Number of prompt types for gathering user input
 * A robust API for getting and validating complex inputs
-* Number of coercion methods for converting response into Ruby types
 
 ## Installation
 
@@ -41,10 +41,12 @@ Or install it yourself as:
 * [1. Usage](#1-usage)
 * [2. Interface](#2-interface)
   * [2.1 ask](#21-ask)
-  * [2.2 read](#22-read)
-  * [2.3 say](#23-say)
-  * [2.4 suggest](#24-suggest)
-
+    * [2.1.1 settings](#211-settings)
+    * [2.1.2 valid read keywords](#212-valid-read-keywords)
+  * [2.2 select](#22-select)
+  * [2.3 multi_select](#23-multi_select)
+  * [2.4 say](#25-say)
+  * [2.5 suggest](#26-suggest)
 
 ## 1. Usage
 
@@ -54,101 +56,263 @@ In order to start asking questions on the command line, create prompt:
 prompt = TTY::Prompt.new
 ```
 
-and then call `ask` with the question message:
+and then call `ask` with the question for simple input:
 
 ```ruby
-question = prompt.ask('Do you like Ruby?')
+prompt.ask('Do you like Ruby?', type: :bool) # => true
 ```
 
-Finally, read and convert answer back to Ruby built-in type:
+Asking question with list of options couldn't be easier using `select` like so:
 
 ```ruby
-answer = question.read_bool
+prompt.select("Choose your destiny?", %w(Scorpion Kano Jax))
+# =>
+# Choose your destiny? (Use arrow keys, press Enter to select)
+# ‣ Scorpion
+#   Kano
+#   Jax
+```
+
+Also, asking multiple choice questions is a breeze with `multi_select`:
+
+```ruby
+choices = %w(vodka beer wine whisky bourbon)
+prompt.select("Select drinks?", choices)
+# =>
+#
+# Select drinks? (Use arrow keys, press Space to select and Enter to finish)"
+# ‣ ⬡ vodka
+#   ⬡ beer
+#   ⬡ wine
+#   ⬡ whisky
+#   ⬡ bourbon
 ```
 
 ## 2. Interface
 
 ### 2.1 ask
 
-In order to ask a basic question and parse an answer do:
+In order to ask a basic question with a string answer do:
 
 ```ruby
-answer = prompt.ask("What is your name?").read_string
+answer = prompt.ask("What is your name?")
 ```
 
-The **TTY::Prompt** provides small DSL to help with parsing and asking precise questions
+In order to prompt for more complex input you can use robust API by passing hash of properties or using block:
+
+```ruby
+prompt.ask("What is your name?") do |q|
+  q.required true
+  q.validate /\A\w+\Z/
+  q.modify   :capitalize
+end
+```
+
+#### 2.1.1 settings
+
+Below is a list of the settings that may be used for customizing `ask` method behaviour:
 
 ```ruby
-argument   # :required or :optional
 char       # 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)
+in         # specify range '0-9', '0..9', '0...9' or negative '-1..-9'
 mask       # mask characters i.e '****' (default: false)
 modify     # apply answer modification :upcase, :downcase, :trim, :chomp etc..
-in         # 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
+read       # Specifies the type of input such as :bool, :string [see](#211-valid-read-keywords)
+required   # If true, value entered must be non-empty (default: false)
+validate   # regex, proc against which stdin input is checked
 ```
 
-You can chain question methods or configure them inside a block:
+Validate setting can take `Regex`, `Proc` like so:
 
 ```ruby
-prompt.ask("What is your name?").argument(:required).default('Piotr').validate(/\w+\s\w+/).read_string
+prompt.ask('What is your username?') { |q|
+  q.validate { |input| input =~ (/^[^\.]+\.[^\.]+/) }
+}
+```
+
+For example, if we wanted to ask a user for a single digit in given range
 
-prompt.ask "What is your name?" do
-  argument :required
-  default  'Piotr'
-  validate /\w+\s\w+/
-  valid    ['Piotr', 'Piotrek']
-  modify   :capitalize
-end.read_string
+```ruby
+ask("Provide number in range: 0-9") { |q| q.in('0-9') }
 ```
 
-### 2.2 read
+#### 2.1.2 valid read keywords
 
-To start reading the input from stdin simply call `read` method:
+The most common thing to do is to cast the answer to specific type. The `read` property is used for that. By default `:string` answer is assumed but this can be changed using one of the following custom readers:
 
 ```ruby
-prompt.read
+:bool       # true or false for strings such as "Yes", "No"
+:char       # first character
+:date       # date type
+:datetime   # datetime type
+:email      # validate answer against email regex
+:file       # a File object
+:float      # decimal or error if cannot convert
+:int        # integer or error if cannot convert
+:multiline  # multiple line string
+:password   # string with echo turned off
+:range      # range type
+:regex      # regex expression
+:string     # string
+:symbol     # symbol
+:text       # multiline string
+:keypress   # the key pressed
 ```
 
-However, there will be cases when your codebase expects answer to be of certain type. **TTY::Prompt** allows reading of answers and converting them into required types with custom readers:
+For example, if you are interested in range type as answer do the following:
 
 ```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
-read_keypress   # return the key pressed
+ask("Provide range of numbers?", read: :range)
 ```
 
-For example, if we wanted to ask a user for a single digit in given range
+### 2.2 select
+
+For asking questions involving list of options use `select` method by passing the question and possible choices:
+
+```ruby
+prompt.select("Choose your destiny?", %w(Scorpion Kano Jax))
+# =>
+# Choose your destiny? (Use arrow keys, press Enter to select)
+# ‣ Scorpion
+#   Kano
+#   Jax
+```
+
+You can also provide options through DSL using the `choice` method for single entry and/or `choices` call for more than one choice:
+
+```ruby
+prompt.select("Choose your destiny?") do |menu|
+  menu.choice 'Scorpion'
+  menu.choice 'Kano'
+  menu.choice 'Jax'
+end
+# =>
+# Choose your destiny? (Use arrow keys, press Enter to select)
+# ‣ Scorpion
+#   Kano
+#   Jax
+```
+
+By default the choice name is used as return value, but you can provide your custom values:
+
+```ruby
+prompt.select("Choose your destiny?") do |menu|
+  menu.choice 'Scorpion', 1
+  menu.choice 'Kano', 2
+  menu.choice 'Jax', 3
+end
+# =>
+# Choose your destiny? (Use arrow keys, press Enter to select)
+# ‣ Scorpion
+#   Kano
+#   Jax
+```
+
+If you wish you can also provide a simple hash to denote choice name and its value like so:
 
 ```ruby
-ask("Provide number in range: 0-9").in('0-9') do
-  on_error :retry
-end.read_int
+choices = {'Scorpion' => 1, 'Kano' => 2, 'Jax' => 3}
+prompt.select("Choose your destiny?", choices)
+```
+
+To mark particular answer as selected use `default` with index of the option starting from `1`:
+
+```ruby
+prompt.select("Choose your destiny?") do |menu|
+  menu.default 3
+
+  menu.choice 'Scorpion', 1
+  menu.choice 'Kano', 2
+  menu.choice 'Jax', 3
+end
+# =>
+# Choose your destiny? (Use arrow keys, press Enter to select)
+#   Scorpion
+#   Kano
+# ‣ Jax
+```
+
+You can configure help message, marker like so
+
+```ruby
+choices = %w(Scorpion Kano Jax)
+prompt.select("Choose your destiny?", choices, help: "(Bash keyboard)")
+# =>
+# Choose your destiny? (Bash keyboard)
+# ‣ Scorpion
+#   Kano
+#   Jax
+```
+
+### 2.3 multi_select
+
+For asking questions involving multiple selection list use `multi_select` method by passing the question and possible choices:
+
+```ruby
+choices = %w(vodka beer wine whisky bourbon)
+prompt.select("Select drinks?", choices)
+# =>
+#
+# Select drinks? (Use arrow keys, press Space to select and Enter to finish)"
+# ‣ ⬡ vodka
+#   ⬡ beer
+#   ⬡ wine
+#   ⬡ whisky
+#   ⬡ bourbon
+```
+
+As a return value, the `multi_select` will always return an array by default populated with the names of the choices. If you wish to return custom values for the available choices do:
+
+```ruby
+choices = {vodka: 1, beer: 2, wine: 3, whisky: 4, bourbon: 5}
+prompt.select("Select drinks?", choices)
+
+# Provided that vodka and beer have been selected, the function will return
+# => [1, 2]
+```
+
+Similar to `select` method, you can also provide options through DSL using the `choice` method for single entry and/or `choices` call for more than one choice:
+
+```ruby
+prompt.multi_select("Select drinks?") do |menu|
+  menu.choice :vodka, {score: 1}
+  menu.choice :beer, 2
+  menu.choice :wine, 3
+  menu.choices whisky: 4, bourbon: 5
+end
+```
+
+To mark choice(s) as selected use the `default` option with index(s) of the option(s) starting from `1`:
+
+```ruby
+prompt.multi_select("Select drinks?") do |menu|
+  menu.default 2, 5
+
+  menu.choice :vodka,   {score: 10}
+  menu.choice :beer,    {score: 20}
+  menu.choice :wine,    {score: 30}
+  menu.choice :whisky,  {score: 40}
+  menu.choice :bourbon, {score: 50}
+end
+# =>
+# Select drinks? beer, bourbon
+#   ⬡ vodka
+#   ⬢ beer
+#   ⬡ wine
+#   ⬡ whisky
+# ‣ ⬢ bourbon
 ```
 
-on the other hand, if we are interested in range answer then
+And when you press enter you will see the following selected:
 
 ```ruby
-ask("Provide range of numbers?").read_range
+# Select drinks? beer, bourbon
+# => [{score: 20}, {score: 50}]
 ```
 
-### 2.3 say
+### 2.4 say
 
 To simply print message out to stdout use `say` like so:
 
@@ -164,16 +328,16 @@ prompt.warn         # print message(s) in yellow
 prompt.error        # print message(s) in red
 ```
 
-### 2.4 suggest
+### 2.5 suggest
 
 To suggest possible matches for the user input use `suggest` method like so:
 
 ```ruby
 prompt.suggest('sta', ['stage', 'stash', 'commit', 'branch'])
 # =>
-Did you mean one of these?
-        stage
-        stash
+# Did you mean one of these?
+#         stage
+#         stash
 ```
 
 To cusomize query text presented pass `:single_text` and `:plural_text` options to respectively change the message when one match is found or many.
@@ -182,8 +346,8 @@ To cusomize query text presented pass `:single_text` and `:plural_text` options
 possible = %w(status stage stash commit branch blame)
 prompt.suggest('b', possible, indent: 4, single_text: 'Perhaps you meant?')
 # =>
-Perhaps you meant?
-    blame
+# Perhaps you meant?
+#     blame
 ```
 
 ## Contributing

data/lib/tty/prompt/choice.rb

@@ -0,0 +1,83 @@
+# encoding: utf-8
+
+module TTY
+  class Prompt
+    # A single choice option
+    #
+    # @api public
+    class Choice
+      # The label name
+      #
+      # @api public
+      attr_reader :name
+
+      # Create a Choice instance
+      #
+      # @api public
+      def initialize(name, value)
+        @name  = name
+        @value = value
+      end
+
+      # Create choice from value
+      #
+      # @example
+      #   Choice.from(:option_1)
+      #   Choice.from([:option_1, 1])
+      #
+      # @param [Object] val
+      #   the value to be converted
+      #
+      # @raise [ArgumentError]
+      #
+      # @return [Choice]
+      #
+      # @api public
+      def self.from(val)
+        case val
+        when Choice
+          return val
+        when String, Symbol
+          new(val, val)
+        when Array
+          new("#{val.first}", val.last)
+        when Hash
+          new("#{val.keys.first}", val.values.first)
+        else
+          raise ArgumentError, "#{val} cannot be coerced into Choice"
+        end
+      end
+
+      # Read value and evaluate
+      #
+      # @api public
+      def value
+        case @value
+        when Proc
+          @value.call
+        else
+          @value
+        end
+      end
+
+      # Object equality comparison
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def ==(other)
+        return false unless other.is_a?(self.class)
+        name == other.name && value == other.value
+      end
+
+      # Object string representation
+      #
+      # @return [String]
+      #
+      # @api public
+      def to_s
+        "#{name}"
+      end
+    end # Choice
+  end # Prompt
+end # TTY

data/lib/tty/prompt/choices.rb

@@ -0,0 +1,92 @@
+# encoding: utf-8
+
+require 'forwardable'
+
+module TTY
+  class Prompt
+    # A class responsible for storing a collection of choices
+    #
+    # @api private
+    class Choices
+      include Enumerable
+      extend Forwardable
+
+      # The actual collection choices
+      #
+      # @return [Array[Choice]]
+      #
+      # @api public
+      attr_reader :choices
+
+      def_delegators :choices, :length, :size, :to_ary, :empty?, :values_at
+
+      # Convenience for creating choices
+      #
+      # @param [Array[Object]] choices
+      #   the choice objects
+      #
+      # @return [Choices]
+      #   the choices collection
+      #
+      # @api public
+      def self.[](*choices)
+        new(choices)
+      end
+
+      # Create Choices collection
+      #
+      # @param [Array[Choice]] choices
+      #   the choices to add to collection
+      #
+      # @api public
+      def initialize(choices = [])
+        @choices = choices.map do |choice|
+          Choice.from(choice)
+        end
+      end
+
+      # Iterate over all choices in the collection
+      #
+      # @yield [Choice]
+      #
+      # @api public
+      def each(&block)
+        return to_enum unless block_given?
+        choices.each(&block)
+      end
+
+      # Add choice to collection
+      #
+      # @param [Object] choice
+      #   the choice to add
+      #
+      # @api public
+      def <<(choice)
+        choices << Choice.from(choice)
+      end
+
+      # Access choice by index
+      #
+      # @param [Integer] index
+      #
+      # @return [Choice]
+      #
+      # @api public
+      def [](index)
+        @choices[index]
+      end
+
+      # Pluck a choice by its name from collection
+      #
+      # @param [String] name
+      #   the label name for the choice
+      #
+      # @return [Choice]
+      #
+      # @api public
+      def pluck(name)
+        find { |choice| choice.name == name }
+      end
+    end # Choices
+  end # Prompt
+end # TTY

data/lib/tty/prompt/codes.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+
+module TTY
+  class Prompt
+    module Codes
+      BACKSPACE = "\177"
+      DELETE   = "\004"
+      ESCAPE   = "\e"
+      LINEFEED = "\n"
+      RETURN   = "\r"
+      SPACE    = " "
+      TAB      = "\t"
+
+      KEY_UP        = "\e[A"
+      KEY_DOWN      = "\e[B"
+      KEY_RIGHT     = "\e[C"
+      KEY_LEFT      = "\e[D"
+      KEY_DELETE    = "\e[3"
+
+      CTRL_J = "\x0A"
+      CTRL_N = "\x0E"
+      CTRL_K = "\x0B"
+      CTRL_P = "\x10"
+      SIGINT = "\x03"
+
+      ITEM_SECURE     = "•"
+      ITEM_SELECTED   = "‣"
+      RADIO_CHECKED   = "⬢"
+      RADIO_UNCHECKED = "⬡"
+    end # Codes
+  end # Prompt
+end # TTY