tty-prompt 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 90f71ba30290379f0e69eb5ff8affb0276d15507
-  data.tar.gz: c16aecac4d1203614dacf82287c2ec7f6f4e8ffd
+SHA256:
+  metadata.gz: 6dde0a99b670047f5cd262c047451d003dfc47ed8179bcd8b4f5e826612baeb8
+  data.tar.gz: 2b9dca2f4d4790a157f30457dd1e5d4c1696aaaf29327624ee886342e67acec5
 SHA512:
-  metadata.gz: bfc62f62785695cf6efa2987acce5bbba00dcfcfe05c33a7641517178017f5a12ec1b600a20e650cf133babea6f6cfe2de8e926f5f9c55d7213b8fb0b0e87d05
-  data.tar.gz: c1e1333370fb6bed3d61fc684788be691698598399358ea5d7354954d9e05604a62871affa17c202e94d6d51d2afe2923f698661d2fb1496b1b06ab966c9f916
+  metadata.gz: d7504991bca7514addf3b72afdd2fcbf3e811528d06e9dede50edc7c80398a1cc486e6662162094afe5eb06657df14fa06082d59b4e587ed2afeac66af7f1e6b
+  data.tar.gz: d6ab20ddeae00214b47428e6c5f9a65aa756d08466e5bf68e84acf6f58cba975d81ad4f99ffa687190694e7bd158e5a82c9af9c6bb74c802344aeb6f2badf628

data/.travis.yml

@@ -11,6 +11,7 @@ rvm:
   - 2.2.8
   - 2.3.6
   - 2.4.3
+  - 2.5.0
   - ruby-head
   - jruby-9000
   - jruby-9.1.1.0

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Change log
 
+## [v0.16.0] - 2018-03-11
+
+### Added
+* Add :disabled key to Choice
+* Add ability to disable choices in #select, #multi_selct & #enum_select prompts
+* Add #frozen_string_literal to all files
+
+### Changed
+* Change Choice#from to allow parsing different data strucutures
+* Change all classes to prevent strings mutations
+* Change Timeout to cleanly terminate keypress input without raising errors
+
+### Fixed
+* Fix #select, #enum_select & #multi_select navigation to work correctly with items longer than terminal screen width
+* Fix timeout on Ruby 2.5 and stop raising Timeout::Error
+
 ## [v0.15.0] - 2018-02-08
 
 ### Added
@@ -245,6 +261,7 @@
 
 * Initial implementation and release
 
+[v0.16.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.15.0...v0.16.0
 [v0.15.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.14.0...v0.15.0
 [v0.14.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.13.2...v0.14.0
 [v0.13.2]: https://github.com/piotrmurach/tty-prompt/compare/v0.13.1...v0.13.2

data/Gemfile

@@ -7,9 +7,8 @@ gemspec
 
 group :test do
   gem 'benchmark-ips', '~> 2.7.2'
-  gem 'simplecov', '~> 0.10.0'
-  gem 'coveralls', '~> 0.8.2'
-  gem 'term-ansicolor', '=1.3.2'
+  gem 'simplecov', '~> 0.14.1'
+  gem 'coveralls', '~> 0.8.21'
 end
 
 group :tools do

data/README.md

@@ -68,16 +68,20 @@ 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.2.1 :timeout](#221-timeout)
   * [2.3 multiline](#23-multiline)
   * [2.4 mask](#24-mask)
   * [2.5 yes?/no?](#25-yesno)
   * [2.6 menu](#26-menu)
-    * [2.6.1 select](#261-select)
-    * [2.6.2 multi_select](#262-multi_select)
-    * [2.6.2.1 echo](#2621-echo)
-    * [2.6.2.2 filter](#2622-filter)
-    * [2.6.3 enum_select](#263-enum_select)
+    * [2.6.1 choices](#261-choices)
+    * [2.6.1.1 :disabled](#2611-disabled)
+    * [2.6.2 select](#262-select)
+      * [2.6.2.1 :disabled](#2621-disabled)
+      * [2.6.2.2 :filter](#2622-filter)
+    * [2.6.3 multi_select](#263-multi_select)
+      * [2.6.3.1 :echo](#2631-echo)
+      * [2.6.3.2 :filter](#2632-filter)
+    * [2.6.4 enum_select](#264-enum_select)
   * [2.7 expand](#27-expand)
   * [2.8 collect](#28-collect)
   * [2.9 suggest](#29-suggest)
@@ -510,7 +514,65 @@ Similarly to `yes?` method, you can supply the same options to customize the que
 
 ### 2.6 menu
 
-### 2.6.1 select
+### 2.6.1 choices
+
+There are many ways in which you can add menu choices. The simplest way is to create an array of values:
+
+```ruby
+choices = %w(small medium large)
+```
+
+By default the choice name is also the value the prompt will return when selected. To provide custom values, you can provide a hash with keys as choice names and their respective values:
+
+```ruby
+choices = {small: 1, medium: 2, large: 3}
+```
+
+Finally, you can define an array of choices where each choice is a hash value with `:name` & `:value` keys which can include other options for customising indvidual choices:
+
+```ruby
+choices = [
+  {name: 'small', value: 1},
+  {name: 'medium', value: 2, disabled: '(out of stock)'},
+  {name: 'large', value: 3}
+]
+```
+
+You can specify `:key` as an additional option which will be used as short name for selecting the choice via keyboard key press.
+
+Another way to create menu with choices is using the DSL and the `choice` method. For example, the previous array of choices with hash values can be translated as:
+
+```ruby
+prompt.select('What size?') do |menu|
+  menu.choice name: 'small',  value: 1
+  menu.choice name: 'medium', value: 2, disabled: '(out of stock)'
+  menu.choice name: 'large',  value: 3
+end
+```
+
+or in a more compact way:
+
+```ruby
+prompt.select('What size?') do |menu|
+  menu.choice 'small', 1
+  menu.choice 'medium', 2, disabled: '(out of stock)'
+  menu.choice 'large', 3
+end
+```
+
+#### 2.6.1.1 `:disabled`
+
+The `:disabled` key indicates to display a choice as currently unavailable to select. Disabled choices are displayed with a cross `✘` character next to them. If the choice is disabled, it cannot be selected. The value for the `:disabled` is used next to the choice to provide reason for excluding it from the selection menu. For example:
+
+```ruby
+choices = [
+  {name: 'small', value: 1},
+  {name: 'medium', value: 2, disabled: '(out of stock)'}
+  {name: 'large', value: 3}
+]
+```
+
+### 2.6.2 select
 
 For asking questions involving list of options use `select` method by passing the question and possible choices:
 
@@ -641,7 +703,73 @@ prompt.select("Choose your letter?") do |menu|
 end
 ```
 
-### 2.6.2 multi_select
+#### 2.6.2.1 `:disabled`
+
+To disable menu choice, use the `:disabled` key with a value that explains the reason for the choice being unavailable. For example, out of all warriors, the Goro is currently injured:
+
+```ruby
+warriors = [
+  'Scorpion',
+  'Kano',
+  { name: 'Goro', disabled: '(injury)' },
+  'Jax',
+  'Kitana',
+  'Raiden'
+]
+```
+
+The disabled choice will be displaed with a cross `✘` character next to it and followed by an explanation:
+
+```ruby
+prompt.select('Choose your destiny?', warriors)
+# =>
+# Choose your destiny? (Use arrow keys, press Enter to select)
+# ‣ Scorpion
+#   Kano
+# ✘ Goro (injury)
+#   Jax
+#   Kitana
+#   Raiden
+```
+
+#### 2.6.2.2 `:filter`
+
+To activate dynamic list searching on letter/number key presses use `:filter` option:
+
+```ruby
+warriors = %w(Scorpion Kano Jax Kitana Raiden)
+prompt.select('Choose your destiny?', warriors, filter: true)
+# =>
+# Choose your destiny? (Use arrow keys, press Enter to select, and letter keys to filter)
+# ‣ Scorpion
+#   Kano
+#   Jax
+#   Kitana
+#   Raiden
+```
+
+After the user presses "k":
+
+```ruby
+# =>
+# Choose your destiny? (Filter: "k")
+# ‣ Kano
+#   Kitana
+```
+
+After the user presse "ka":
+
+```ruby
+# =>
+# Choose your destiny? (Filter: "ka")
+# ‣ Kano
+```
+
+Filter characters can be deleted partially or entirely via, respectively, Backspace and Canc.
+
+If the user changes or deletes a filter, the choices previously selected remain selected.
+
+### 2.6.3 multi_select
 
 For asking questions involving multiple selection list use `multi_select` method by passing the question and possible choices:
 
@@ -762,7 +890,7 @@ prompt.multi_select("Choose your letter?", letters, per_page: 4)
 # (Move up or down to reveal more choices)
 ```
 
-### 2.6.2.1 echo
+### 2.6.3.1 `:echo`
 
 To control whether the selected items are shown on the question
 header use the :echo option:
@@ -779,7 +907,7 @@ prompt.multi_select("Select drinks?", choices, echo: false)
 # ‣ ⬢ 5) bourbon
 ```
 
-### 2.6.2.2 filter
+### 2.6.3.2 `:filter`
 
 To activate dynamic list filtering on letter/number typing, use the :filter option:
 
@@ -797,7 +925,7 @@ prompt.multi_select("Select drinks?", choices, filter: true)
 
 After the user presses "w":
 
-```
+```ruby
 # Select drinks? (Filter: "w")
 # ‣ ⬡ wine
 #   ⬡ whisky
@@ -809,7 +937,7 @@ If the user changes or deletes a filter, the choices previously selected remain
 
 The `filter` option is not compatible with `enum`.
 
-### 2.6.3 enum_select
+### 2.6.4 enum_select
 
 In order to ask for standard selection from indexed list you can use `enum_select` and pass question together with possible choices:
 

data/appveyor.yml

@@ -19,3 +19,4 @@ environment:
     - ruby_version: "23-x64"
     - ruby_version: "24"
     - ruby_version: "24-x64"
+    - ruby_version: "25-x64"

data/examples/enum_select_disabled.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+require_relative "../lib/tty-prompt"
+
+prompt = TTY::Prompt.new
+
+choices = [
+  "Atom",
+  {name: "Emacs", disabled: '(not installed)'},
+  "GNU nano",
+  {name: "Notepad++", disabled: '(not installed)'},
+  "Sublime",
+  "Vim"
+]
+
+prompt.enum_select('Select an editor', choices)

data/examples/enum_select_wrapped.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+require_relative '../lib/tty-prompt'
+
+prompt = TTY::Prompt.new
+
+quotes = [
+  "There are certain queer times and occasions in this strange mixed affair we call life when a man takes this whole universe for a vast practical joke, though the wit thereof he but dimly discerns, and more than suspects that the joke is at nobody's expense but his own.",
+  "Talk not to me of blasphemy, man;\n I'd strike the sun if it insulted me.",
+  "There is a wisdom that is woe; but there is a woe that is madness. And there is a Catskill eagle in some souls that can alike dive down into the blackest gorges, and soar out of them again and become invisible in the sunny spaces. And even if he for ever flies within the gorge, that gorge is in the mountains; so that even in his lowest swoop the mountain eagle is still higher than other birds upon the plain, even though they soar."
+]
+
+answer = prompt.enum_select('Chose your quote?', quotes)
+
+puts "Answer: #{answer}"

data/examples/multi_select_disabled.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+
+require_relative "../lib/tty-prompt"
+
+prompt = TTY::Prompt.new
+
+drinks = [
+  {name: 'sake', disabled: '(out of stock)'},
+  'vodka',
+  {name: 'beer', disabled: '(out of stock)'},
+  'wine',
+  'whisky',
+  'bourbon'
+]
+answer = prompt.multi_select('Choose your favourite drink?', drinks, default: 2)
+
+puts answer.inspect

data/examples/multi_select_wrapped.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+require_relative '../lib/tty-prompt'
+
+prompt = TTY::Prompt.new
+
+quotes = [
+  "There are certain queer times and occasions in this strange mixed affair we call life when a man takes this whole universe for a vast practical joke, though the wit thereof he but dimly discerns, and more than suspects that the joke is at nobody's expense but his own.",
+  "Talk not to me of blasphemy, man; I'd strike the sun if it insulted me.",
+  "There is a wisdom that is woe; but there is a woe that is madness. And there is a Catskill eagle in some souls that can alike dive down into the blackest gorges, and soar out of them again and become invisible in the sunny spaces. And even if he for ever flies within the gorge, that gorge is in the mountains; so that even in his lowest swoop the mountain eagle is still higher than other birds upon the plain, even though they soar."
+]
+
+answer = prompt.multi_select('Choose your quote?', quotes, echo: false)
+
+puts "Answer: #{answer}"

data/examples/select.rb

@@ -15,4 +15,6 @@ prompt.on(:keypress) do |event|
   end
 end
 
-prompt.select('Choose your destiny?', warriors)
+answer = prompt.select('Choose your destiny?', warriors)
+
+puts answer.inspect

data/examples/select_disabled.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+require_relative "../lib/tty-prompt"
+
+prompt = TTY::Prompt.new
+
+warriors = [
+  'Scorpion',
+  'Kano',
+  { name: 'Goro', disabled: '(injury)' },
+  'Jax',
+  'Kitana',
+  'Raiden'
+]
+
+answer = prompt.select('Choose your destiny?', warriors, enum: ')')
+
+puts answer.inspect

data/examples/select_filtered.rb

@@ -6,4 +6,6 @@ prompt = TTY::Prompt.new
 
 warriors = %w(Scorpion Kano Jax Kitana Raiden)
 
-prompt.select('Choose your destiny?', warriors, filter: true)
+answer = prompt.select('Choose your destiny?', warriors, filter: true)
+
+puts answer.inspect

data/examples/select_paginated.rb

@@ -6,4 +6,6 @@ prompt = TTY::Prompt.new
 
 alfabet = ('A'..'Z').to_a
 
-prompt.select('Which letter?', alfabet, per_page: 8)
+answer = prompt.select('Which letter?', alfabet, per_page: 8)
+
+puts answer.inspect

data/examples/select_wrapped.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+require_relative '../lib/tty-prompt'
+
+prompt = TTY::Prompt.new
+
+quotes = [
+  "There are certain queer times and occasions in this strange mixed affair we call life when a man takes this whole universe for a vast practical joke, though the wit thereof he but dimly discerns, and more than suspects that the joke is at nobody's expense but his own.",
+  "Talk not to me of blasphemy, man;\n I'd strike the sun if it insulted me.",
+  "There is a wisdom that is woe; but there is a woe that is madness. And there is a Catskill eagle in some souls that can alike dive down into the blackest gorges, and soar out of them again and become invisible in the sunny spaces. And even if he for ever flies within the gorge, that gorge is in the mountains; so that even in his lowest swoop the mountain eagle is still higher than other birds upon the plain, even though they soar."
+]
+
+answer = prompt.select('Chose your quote?', quotes)
+
+puts "Answer: #{answer}"

data/lib/tty/prompt.rb

@@ -1,4 +1,5 @@
 # encoding: utf-8
+# frozen_string_literal: true
 
 require 'forwardable'
 require 'pastel'

data/lib/tty/prompt/answers_collector.rb

@@ -1,4 +1,5 @@
 # encoding: utf-8
+# frozen_string_literal: true
 
 module TTY
   class Prompt

data/lib/tty/prompt/choice.rb

@@ -1,32 +1,23 @@
 # encoding: utf-8
+# frozen_string_literal: true
 
 module TTY
   class Prompt
-    # A single choice option
+    # An immutable representation of a single choice option from select menu
     #
     # @api public
     class Choice
-      # The label name
+      # Create choice from value
       #
-      # @api public
-      attr_reader :name
-
-      attr_reader :key
-
-      # Create a Choice instance
+      # @examples
+      #   Choice.from(:foo)
+      #   # => <TTY::Prompt::Choice @key=nil @name="foo" @value="foo" @disabled=false>
       #
-      # @api public
-      def initialize(name, value, key = nil)
-        @name  = name
-        @value = value
-        @key   = key
-      end
-
-      # Create choice from value
+      #   Choice.from([:foo, 1])
+      #   # => <TTY::Prompt::Choice @key=nil @name="foo" @value=1 @disabled=false>
       #
-      # @example
-      #   Choice.from(:option_1)
-      #   Choice.from([:option_1, 1])
+      #   Choice.from({name: :foo, value: 1, key: 'f'}
+      #   # => <TTY::Prompt::Choice @key="f" @name="foo" @value=1 @disabled=false>
       #
       # @param [Object] val
       #   the value to be converted
@@ -43,18 +34,67 @@ module TTY
         when String, Symbol
           new(val, val)
         when Array
-          new("#{val.first}", val.last)
-        when Hash
-          if val.key?(:name)
-            new("#{val[:name]}", val[:value], val[:key])
+          name, value, options = *val
+          if name.is_a?(Hash)
+            convert_hash(name)
           else
-            new("#{val.keys.first}", val.values.first)
+            new(name.to_s, value || name.to_s, options || {})
           end
+        when Hash
+          convert_hash(val)
         else
           raise ArgumentError, "#{val} cannot be coerced into Choice"
         end
       end
 
+      # Convert hash into choice
+      #
+      # @api public
+      def self.convert_hash(val)
+        if val.key?(:name) && val.key?(:value)
+          new(val[:name].to_s, val[:value], val)
+        elsif val.key?(:name)
+          new(val[:name].to_s, val[:name].to_s, val)
+        else
+          new(val.keys.first.to_s, val.values.first)
+        end
+      end
+
+      # The label name
+      #
+      # @api public
+      attr_reader :name
+
+      # The keyboard key to activate this choice
+      #
+      # @api public
+      attr_reader :key
+
+      # The text to display for disabled choice
+      #
+      # @api public
+      attr_reader :disabled
+
+      # Create a Choice instance
+      #
+      # @api public
+      def initialize(name, value, **options)
+        @name  = name
+        @value = value
+        @key   = options[:key]
+        @disabled = options[:disabled].nil? ? false : options[:disabled]
+        freeze
+      end
+
+      # Check if this choice is disabled
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def disabled?
+        !!@disabled
+      end
+
       # Read value and evaluate
       #
       # @api public
@@ -74,7 +114,9 @@ module TTY
       # @api public
       def ==(other)
         return false unless other.is_a?(self.class)
-        name == other.name && value == other.value
+        name == other.name &&
+        value == other.value &&
+        key == other.key
       end
 
       # Object string representation