tty-prompt 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b2e80fd1b397f9aae2abb3195844a6d1d3dc2dea
-  data.tar.gz: 266c5ccc26bcbe7ea0a9634e7f702e3387a2bce4
+  metadata.gz: 4a61159db722c1c9c3be87b952db58198825cda3
+  data.tar.gz: bf536fe71b19528ee38f2fea21efae414c32bb2b
 SHA512:
-  metadata.gz: d249d03ac3dd16fc49b784e5d11983f31c15d30991c524fe6dbc1fd135c7509fef3476f1ef3b1ad4c5e1dd9bcf19ec938743771c4f121fcf96977b3913220ab2
-  data.tar.gz: eacb6d537e03baaf4219304af247d0baaf24f0d22efd2e49eec368d5f19a4f5449ec10af4ca9009eba2dc468b91d22580b5df47333c519b759ba010e8505d394
+  metadata.gz: f90ed4437bd6d5d7a14230ea1d0b31fc41129333c11ab65c0a6473f1f60ad938bc3b66061f103dc42c179df8464ac24263332e0fc2b6ce31a65e3c5990a472a8
+  data.tar.gz: 55b5ffcfc01d21d0584a9e630c9544a5314701091e4d9d6733be5284d1d134e7c09274335efe07aa8c794c0167b6599b295343a9ddb40a1b63728c2901852fc8

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Change log
 
+## [v0.5.0] - 2016-03-28
+
+### Added
+* Add ConfirmQuestion for #yes? & #no? calls
+* Add ability to collect more than one answer through #collect call
+* Add Choices#find_by for selecting choice based on attribute
+* Add Prompt#expand for expanding key options
+* Add :active_color, :help_color, :prefix options for customizing prompts display
+
+### Changed
+* Change Choice#from to allow for coersion of complex objects with keys
+* Change Choices#pluck to search through object attributes
+* Change #select :enum option help text to display actual numbers range
+
+### Fixed
+* Fix #no? to correctly ask negative question by @ondra-m
+* Fix #ask :default option to handle nil or empty string
+* Fix #multi_select :default option and color changing
+
 ## [v0.4.0] - 2016-02-08
 
 ### Added
@@ -58,6 +77,7 @@
 
 * Initial implementation and release
 
+[v0.5.0]: https://github.com/peter-murach/tty-prompt/compare/v0.4.0...v0.5.0
 [v0.4.0]: https://github.com/peter-murach/tty-prompt/compare/v0.3.0...v0.4.0
 [v0.3.0]: https://github.com/peter-murach/tty-prompt/compare/v0.2.0...v0.3.0
 [v0.2.0]: https://github.com/peter-murach/tty-prompt/compare/v0.1.0...v0.2.0

data/Gemfile

@@ -2,14 +2,18 @@ source 'https://rubygems.org'
 
 gemspec
 
-group :tools do
-  gem 'yard',  '~> 0.8.7'
+group :test do
+  gem 'rspec',     '~> 3.4.0'
   gem 'benchmark-ips', '~> 2.0.0'
+  gem 'simplecov', '~> 0.10.0'
+  gem 'coveralls', '~> 0.8.2'
+end
+
+group :tools do
   gem 'byebug', platform: :mri
 end
 
 group :metrics do
-  gem 'coveralls', '~> 0.8.2'
-  gem 'simplecov', '~> 0.10.0'
+  gem 'yard',      '~> 0.8.7'
   gem 'yardstick', '~> 0.9.9'
 end

data/README.md

@@ -1,19 +1,19 @@
 # TTY::Prompt
 [![Gem Version](https://badge.fury.io/rb/tty-prompt.svg)][gem]
-[![Build Status](https://secure.travis-ci.org/peter-murach/tty-prompt.svg?branch=master)][travis]
-[![Code Climate](https://codeclimate.com/github/peter-murach/tty-prompt/badges/gpa.svg)][codeclimate]
-[![Coverage Status](https://coveralls.io/repos/peter-murach/tty-prompt/badge.svg)][coverage]
-[![Inline docs](http://inch-ci.org/github/peter-murach/tty-prompt.svg?branch=master)][inchpages]
+[![Build Status](https://secure.travis-ci.org/piotrmurach/tty-prompt.svg?branch=master)][travis]
+[![Code Climate](https://codeclimate.com/github/piotrmurach/tty-prompt/badges/gpa.svg)][codeclimate]
+[![Coverage Status](https://coveralls.io/repos/piotrmurach/tty-prompt/badge.svg)][coverage]
+[![Inline docs](http://inch-ci.org/github/piotrmurach/tty-prompt.svg?branch=master)][inchpages]
 
 [gem]: http://badge.fury.io/rb/tty-prompt
-[travis]: http://travis-ci.org/peter-murach/tty-prompt
-[codeclimate]: https://codeclimate.com/github/peter-murach/tty-prompt
-[coverage]: https://coveralls.io/r/peter-murach/tty-prompt
-[inchpages]: http://inch-ci.org/github/peter-murach/tty-prompt
+[travis]: http://travis-ci.org/piotrmurach/tty-prompt
+[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-prompt
+[coverage]: https://coveralls.io/r/piotrmurach/tty-prompt
+[inchpages]: http://inch-ci.org/github/piotrmurach/tty-prompt
 
 > A beautiful and powerful interactive command line prompt.
 
-**TTY::Prompt** provides independent prompt component for [TTY](https://github.com/peter-murach/tty) toolkit.
+**TTY::Prompt** provides independent prompt component for [TTY](https://github.com/piotrmurach/tty) toolkit.
 
 ## Features
 
@@ -51,6 +51,9 @@ Or install it yourself as:
     * [2.2.6 required](#226-required)
     * [2.2.7 validate](#227-validate)
     * [2.2.8 messages](#228-messages)
+    * [2.2.9 prefix](#229-prefix)
+    * [2.2.10 active_color](#2210-active_color)
+    * [2.2.11 help_color](#2211-help_color)
   * [2.3 keypress](#23-keypress)
   * [2.4 multiline](#24-multiline)
   * [2.5 mask](#25-mask)
@@ -58,12 +61,14 @@ Or install it yourself as:
   * [2.7 select](#27-select)
   * [2.8 multi_select](#28-multi_select)
   * [2.9 enum_select](#29-enum_select)
-  * [2.10 suggest](#210-suggest)
-  * [2.11 slider](#211-slider)
-  * [2.12 say](#212-say)
-  * [2.13 ok](#213-ok)
-  * [2.14 warn](#214-warn)
-  * [2.15 error](#215-warn)
+  * [2.10 expand](#210-expand)
+  * [2.11 collect](#211-collect)
+  * [2.12 suggest](#212-suggest)
+  * [2.13 slider](#213-slider)
+  * [2.14 say](#214-say)
+  * [2.15 ok](#215-ok)
+  * [2.16 warn](#216-warn)
+  * [2.17 error](#217-warn)
 
 ## 1. Usage
 
@@ -124,7 +129,7 @@ To ask for a selection from enumerated list you can use `enum_select`:
 
 ```ruby
 choices = %w(emacs nano vim)
-prompt.enum_select("Select an editor?")
+prompt.enum_select("Select an editor?", choices)
 # =>
 #
 # Select an editor?
@@ -134,6 +139,39 @@ prompt.enum_select("Select an editor?")
 #   Choose 1-3 [2]:
 ```
 
+However, if you have a lot of options to choose from you may want to use `expand`:
+
+```ruby
+choices = [
+  { key: 'y', name: 'overwrite this file', value: :yes },
+  { key: 'n', name: 'do not overwrite this file', value: :no },
+  { key: 'a', name: 'overwrite this file and all later files', value: :all },
+  { key: 'd', name: 'show diff', value: :diff },
+  { key: 'q', name: 'quit; do not overwrite this file ', value: :quit }
+]
+prompt.expand('Overwrite Gemfile?', choices)
+# =>
+# Overwrite Gemfile? (enter "h" for help) [y,n,a,d,q,h]
+```
+
+If you wish to collect more than one answer use `collect`:
+
+```ruby
+result = prompt.collect do
+  key(:name).ask('Name?')
+
+  key(:age).ask('Age?', convert: :int)
+
+  key(:address) do
+    key(:street).ask('Street?', required: true)
+    key(:city).ask('City?')
+    key(:zip).ask('Zip?', validate: /\A\d{3}\Z/)
+  end
+end
+# =>
+# {:name => "Piotr", :age => 30, :address => {:street => "Street", :city => "City", :zip => "123"}}
+```
+
 ## 2. Interface
 
 ### 2.1 ask
@@ -300,6 +338,32 @@ prompt.ask('What is your email?') do |q|
 end
 ```
 
+### 2.2.9 prefix
+
+You can prefix each question asked using the `:prefix` option. This option can be applied either globally for all prompts or individual for each one:
+
+```ruby
+prompt = TTY::Prompt.new(prefix: '[?] ')
+```
+
+### 2.2.10 active_color
+
+All prompt types support `:active_color` option. In case of `select`, `multi_select`, `enum_select` or `expand` this color is used to highlight the currently selected choice. All the resulted inputs provided by user that are read in by the prompt as answer are highlighted with this color. This option can be applied either globablly for all prompts or individually.
+
+```ruby
+prompt.select('What size?', %w(Large Medium Small), active_color: :cyan)
+```
+
+Please (see pastel)[https://github.com/piotrmurach/pastel#3-supported-colors] for all supported colors.
+
+### 2.2.11 help_color
+
+Prompts such as `select`, `multi_select`, `expand` support `:help_color` which is used to customize the help text. This option can be applied either globablly for all prompts or individually.
+
+```ruby
+prompt.select('What size?', %w(Large Medium Small), help_color: :cyan)
+```
+
 ### 2.3 keypress
 
 In order to ask question with a single character or keypress answer use `keypress`:
@@ -350,13 +414,44 @@ prompt.yes?('Do you like Ruby?')
 # Do you like Ruby? (Y/n)
 ```
 
-the same can be achieved by using plain `ask`:
+You can further customize question by passing `suffix`, `positive`, `negative` and `convert` options. The `suffix` changes text of available options, the `positive` specifies display string for successful answer and `negative` changes display string for negative answer. The final value is a boolean provided the `convert` option evaluates to boolean.
+
+It's enough to provide the `suffix` option for the prompt to accept matching answers with correct labels:
 
 ```ruby
-prompt.ask('Do you like Ruby? (Y/n)', convert: :bool)
+prompt.yes?("Are you a human?") do |q|
+  q.suffix 'Yup/nope'
+end
+# =>
+# Are you a human? (Yup/nope)
 ```
 
-There is also the opposite for asking confirmation of negative option:
+Alternatively, instead of `suffix` option provide the `positive` and `negative` labels:
+
+```ruby
+prompt.yes?("Are you a human?") do |q|
+  q.default false
+  q.positive 'Yup'
+  q.negative 'Nope'
+end
+# =>
+# Are you a human? (yup/Nope)
+```
+
+Finally, providing all available options you can ask fully customized question:
+
+```ruby
+prompt.yes?('Are you a human?') do |q|
+  q.suffix 'Agree/Disagree'
+  q.positive 'Agree'
+  q.negative 'Disagree'
+  q.convert -> (input) { !input.match(/^agree$/i).nil? }
+end
+# =>
+# Are you a human? (Agree/Disagree)
+```
+
+There is also the opposite for asking confirmation of negative question:
 
 ```ruby
 prompt.no?('Do you hate Ruby?')
@@ -364,6 +459,8 @@ prompt.no?('Do you hate Ruby?')
 # Do you hate Ruby? (y/N)
 ```
 
+Similarly to `yes?` method, you can supply the same options to customize the question.
+
 ### 2.7 select
 
 For asking questions involving list of options use `select` method by passing the question and possible choices:
@@ -392,13 +489,13 @@ end
 #   Jax
 ```
 
-By default the choice name is used as return value, but you can provide your custom values:
+By default the choice name is used as return value, but you can provide your custom values including a `Proc` object:
 
 ```ruby
 prompt.select("Choose your destiny?") do |menu|
   menu.choice 'Scorpion', 1
   menu.choice 'Kano', 2
-  menu.choice 'Jax', 3
+  menu.choice 'Jax', -> { 'Nice choice captain!' }
 end
 # =>
 # Choose your destiny? (Use arrow keys, press Enter to select)
@@ -448,14 +545,14 @@ end
 # ‣ 3. Jax
 ```
 
-You can configure help message, marker like so
+You can configure help message and/or marker like so
 
 ```ruby
 choices = %w(Scorpion Kano Jax)
-prompt.select("Choose your destiny?", choices, help: "(Bash keyboard)")
+prompt.select("Choose your destiny?", choices, help: "(Bash keyboard)", marker: '>')
 # =>
 # Choose your destiny? (Bash keyboard)
-# ‣ Scorpion
+# > Scorpion
 #   Kano
 #   Jax
 ```
@@ -547,6 +644,20 @@ And when you press enter you will see the following selected:
 # => [{score: 20}, {score: 50}]
 ```
 
+You can configure help message and/or marker like so
+
+```ruby
+choices = {vodka: 1, beer: 2, wine: 3, whisky: 4, bourbon: 5}
+prompt.select("Select drinks?", choices, help: 'Press beer can against keyboard')
+# =>
+# Select drinks? (Press beer can against keyboard)"
+# ‣ ⬡ vodka
+#   ⬡ beer
+#   ⬡ wine
+#   ⬡ whisky
+#   ⬡ bourbon
+```
+
 ### 2.9 enum_select
 
 In order to ask for standard selection from indexed list you can use `enum_select` and pass question together with possible choices:
@@ -606,7 +717,93 @@ end
 # Select an editor? /usr/bin/vim
 ```
 
-### 2.10 suggest
+### 2.10 expand
+
+The `expand` provides a compact way to ask a question with many options.
+
+As first argument `expand` takes the message to display and as a second an array of choices. Compared to the `select`, `multi_select` and `enum_select`, the choices need to be objects that include `:key`, `:name` and `:value` keys. The `:key` must be a single character. The help choice is added automatically as the last option and the key `h`.
+
+```ruby
+choices = [
+  {
+    key: 'y',
+    name: 'overwrite this file',
+    value: :yes
+  }, {
+    key: 'n',
+    name: 'do not overwrite this file',
+    value: :no
+  }, {
+    key: 'q',
+    name: 'quit; do not overwrite this file ',
+    value: :quit
+  }
+]
+```
+
+The choices can also be provided through DSL using the `choice` method. The `:value` can be a primitive value or `Proc` instance that gets executed and whose value is used as returned type. For example:
+
+```ruby
+prompt.expand('Overwrite Gemfile?') do |q|
+  q.choice key: 'y', name: 'Overwrite'      do :ok end
+  q.choice key: 'n', name: 'Skip',          value: :no
+  q.choice key: 'a', name: 'Overwrite all', value: :all
+  q.choice key: 'd', name: 'Show diff',     value: :diff
+  q.choice key: 'q', name: 'Quit',          value: :quit
+end
+```
+
+The first element in the array of choices or provided via `choice` DSL will be the default choice, you can change that by passing `default` option.
+
+```ruby
+prompt.expand('Overwrite Gemfile?', choices)
+# =>
+# Overwrite Gemfile? (enter "h" for help) [y,n,q,h]
+```
+
+Each time user types an option a hint will be displayed:
+
+```ruby
+# Overwrite Gemfile? (enter "h" for help) [y,n,a,d,q,h] y
+# >> overwrite this file
+```
+
+If user types `h` and presses enter, an expanded view will be shown which further allows to refine the choice:
+
+```ruby
+# Overwrite Gemfile?
+#   y - overwrite this file
+#   n - do not overwrite this file
+#   q - quit; do not overwrite this file
+#   h - print help
+#   Choice [y]:
+```
+
+Run `examples/expand.rb` to see the prompt in action.
+
+### 2.11 collect
+
+In order to collect more than one answer use `collect` method. Using the `key` you can describe the answers key name. All the methods for asking user input such as `ask`, `mask`, `select` can be directly invoked on the key. The key composition is very flexible by allowing nested keys. If you want the value to be automatically converted to required type use [convert](#221-convert).
+
+For example to gather some contact information do:
+
+```ruby
+prompt.collect do
+  key(:name).ask('Name?')
+
+  key(:age).ask('Age?', convert: :int)
+
+  key(:address) do
+    key(:street).ask('Street?', required: true)
+    key(:city).ask('City?')
+    key(:zip).ask('Zip?', validate: /\A\d{3}\Z/)
+  end
+end
+# =>
+# {:name => "Piotr", :age => 30, :address => {:street => "Street", :city => "City", :zip => "123"}}
+```
+
+### 2.12 suggest
 
 To suggest possible matches for the user input use `suggest` method like so:
 
@@ -628,7 +825,7 @@ prompt.suggest('b', possible, indent: 4, single_text: 'Perhaps you meant?')
 #     blame
 ```
 
-### 2.11 slider
+### 2.13 slider
 
 If you have constrained range of numbers for user to choose from you may consider using `slider`. The slider provides easy visual way of picking a value marked by `O` marker.
 
@@ -655,7 +852,7 @@ end
 # |--O-------| 4
 ```
 
-### 2.12 say
+### 2.14 say
 
 To simply print message out to stdout use `say` like so:
 
@@ -663,11 +860,11 @@ To simply print message out to stdout use `say` like so:
 prompt.say(...)
 ```
 
-The `say` method also accepts option `:color` which supports all the colors provided by [pastel](https://github.com/peter-murach/pastel#3-supported-colors)
+The `say` method also accepts option `:color` which supports all the colors provided by [pastel](https://github.com/piotrmurach/pastel#3-supported-colors)
 
 **TTY::Prompt** provides more specific versions of `say` method to better express intenation behind the message such as `ok`, `warn` and `error`.
 
-### 2.13 ok
+### 2.15 ok
 
 Print message(s) in green do:
 
@@ -675,7 +872,7 @@ Print message(s) in green do:
 prompt.ok(...)
 ```
 
-### 2.14 warn
+### 2.16 warn
 
 Print message(s) in yellow do:
 
@@ -683,7 +880,7 @@ Print message(s) in yellow do:
 prompt.warn(...)
 ```
 
-### 2.15 error
+### 2.17 error
 
 Print message(s) in red do:
 
@@ -693,7 +890,7 @@ prompt.error(...)
 
 ## Contributing
 
-1. Fork it ( https://github.com/peter-murach/tty-prompt/fork )
+1. Fork it ( https://github.com/piotrmurach/tty-prompt/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)