tty-prompt 0.19.0 → 0.23.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b95f394284033f244487a624ca98d9d4aca8a1d5b01c08d181a3bbfe509aa4a
-  data.tar.gz: 32031c9ca43c3098418f54051af00bdcba6075532ba0878a3b8efda844ba076f
+  metadata.gz: 69ced9f6a4234a7234fc2dbce1bc17a982afd2922d7a5c30e0f57030c0970e01
+  data.tar.gz: 26835914ed361e5617660f8bbd9106c101d2963a6e7ae335c4c57ed910658773
 SHA512:
-  metadata.gz: decec13d7b8a65ba78d5c2eea5ed3366976670c1a7e0ebe228c25cf5b494aa82fe3131e5521fe3c8d882d10b2db2aa6934749f1583f767630f4bf3a4fc59eb96
-  data.tar.gz: 7d1e877c0f4e1df2db06726cd8748b6e777f59cf055177d480610687db46ad7de12ee7cfe7aa454414816020bfa35ab5a1e273b680946a45d287b6563e7a1ff6
+  metadata.gz: 767a3e943e5740eddbcf14fe9d25fd1d14054402c45d7020762b2cc78842720699223ec27fd229ea70cfb47ab6879b5fd144a76073e44092ed4b8eca1a56e357
+  data.tar.gz: 65b4c4d5ec2d06b900ef4bbd2012eb12c1c1952fe2b7c8ba1865714393da5c34f232a13a35bbefeee870b57d2cb741c77586725bd00a3a1e6a7a61521dfb8c13

data/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Change log
 
+## [v0.23.1] - 2021-04-17
+
+### Changed
+* Change validate to allow access to invalid input inside the message
+
+### Fixed
+* Fix Choice#from to differentiate between no value being set and nil value
+
+## [v0.23.0] - 2020-12-14
+
+### Added
+* Add the ability to provide an arbitrary array of values to Prompt::Slider by Katelyn Schiesser (@slowbro)
+
+### Changed
+* Change to allow default option to be choice name as well as index in select, multi_select and enum_select prompts
+
+### Fixed
+* Fix left and right key navigation while filtering choices in the #select and #multi_select prompts
+
+## [v0.22.0] - 2020-07-20
+
+### Added
+* Add #slider format customization with a proc by Sven Pchnit(@2called-chaos)
+* Add convert message customization
+* Add conversion of input into Array, Hash or URI object
+* Add callable objects as possible values in :active_color and :help_color
+* Add shortcuts to select of all/reverse choices in #multi_select prompt
+* Add :help option to #slider prompt
+* Add :quiet option to remove final prompt output by Katelyn Schiesser (@slowbro)
+* Add :show_help option to control help display in #select, #multi_select, #enum_select
+  and #slider prompts
+
+### Changed
+* Changed question :validation option to :validate by Sven Pachnit(@2called-chaos)
+* Change ConverterRegistry to store only proc values and simplify interface
+* Change Converters to stop raising errors and print console error messages instead
+* Change :range conversion to handle float numbers
+* Change yes?/no? prompt to infer default value from words and raise when
+  no boolean can be deduced
+* Change Prompt#new to use keyword arguments
+* Change #select/#multi_select prompts default help text
+* Change #multi_select to preserve original ordering in returned answers
+* Change to remove necromancer dependency
+* Change TTY::TestPrompt to TTY::Prompt::Test
+* Change #select,#multi_select & #enum_select to allow mix of options and block parameters configuration
+* Change to allow filtering through symbol choice names
+* Change all errors to inherit from common Error class
+
+### Fixed
+* Fix multiline prompt to return default value when no input provided
+* Fix color option overriding in say, ok, error and warn prompts
+* Fix Prompt#inspect format to display all public attributes
+
+## [v0.21.0] - 2020-03-08
+
+### Added
+* Add :min option to #multi_select prompt by Katelyn Schiesser(@slowbro)
+
+### Changed
+* Change gemspec to remove test artifacts
+
+### Fixed
+* Fix :help_color option for multi_select prompt by @robbystk
+
+## [v0.20.0] - 2019-11-24
+
+### Changed
+* Change to update tty-reader dependency
+* Change gemspec to include metadata
+
+### Fixed
+* Fix Choice#from to differentiate between nil and false by Katelyn Schiesser(@slowbro)
+* Fix yes? and no? prompts to stop raising on invalid/blank input by Katelyn Schiesser(@slowbro)
+* Fix Ruby 2.7 keyword arguments warnings
+* Fix question validation to work with nil input
+
 ## [v0.19.0] - 2019-05-27
 
 ### Added
@@ -326,6 +402,11 @@
 
 * Initial implementation and release
 
+[v0.23.1]: https://github.com/piotrmurach/tty-prompt/compare/v0.23.0...v0.23.1
+[v0.23.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.22.0...v0.23.0
+[v0.22.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.21.0...v0.22.0
+[v0.21.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.20.0...v0.21.0
+[v0.20.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.19.0...v0.20.0
 [v0.19.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.18.1...v0.19.0
 [v0.18.1]: https://github.com/piotrmurach/tty-prompt/compare/v0.18.0...v0.18.1
 [v0.18.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.17.2...v0.18.0

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2015 Piotr Murach
+Copyright (c) 2015 Piotr Murach (piotrmurach.com)
 
 MIT License
 

data/README.md

@@ -1,11 +1,11 @@
 <div align="center">
-  <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://cdn.rawgit.com/piotrmurach/tty/master/images/tty.png" alt="tty logo" /></a>
+  <a href="https://ttytoolkit.org"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="TTY Toolkit logo" /></a>
 </div>
 
 # TTY::Prompt [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
 
 [![Gem Version](https://badge.fury.io/rb/tty-prompt.svg)][gem]
-[![Build Status](https://secure.travis-ci.org/piotrmurach/tty-prompt.svg?branch=master)][travis]
+[![Actions CI](https://github.com/piotrmurach/tty-prompt/workflows/CI/badge.svg?branch=master)][gh_actions_ci]
 [![Build status](https://ci.appveyor.com/api/projects/status/4cguoiah5dprbq7n?svg=true)][appveyor]
 [![Code Climate](https://codeclimate.com/github/piotrmurach/tty-prompt/badges/gpa.svg)][codeclimate]
 [![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-prompt/badge.svg)][coverage]
@@ -13,6 +13,7 @@
 
 [gitter]: https://gitter.im/piotrmurach/tty
 [gem]: http://badge.fury.io/rb/tty-prompt
+[gh_actions_ci]: https://github.com/piotrmurach/tty-prompt/actions?query=workflow%3ACI
 [travis]: http://travis-ci.org/piotrmurach/tty-prompt
 [appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-prompt
 [codeclimate]: https://codeclimate.com/github/piotrmurach/tty-prompt
@@ -47,7 +48,7 @@ For Windows, consider installing [ConEmu](https://conemu.github.io/), [cmder](ht
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'tty-prompt'
+gem "tty-prompt"
 ```
 
 And then execute:
@@ -63,15 +64,15 @@ Or install it yourself as:
 * [1. Usage](#1-usage)
 * [2. Interface](#2-interface)
   * [2.1 ask](#21-ask)
-    * [2.1.1 convert](#211-convert)
-    * [2.1.2 default](#212-default)
-    * [2.1.3 value](#213-value)
-    * [2.1.4 echo](#214-echo)
+    * [2.1.1 :convert](#211-convert)
+    * [2.1.2 :default](#212-default)
+    * [2.1.3 :value](#213-value)
+    * [2.1.4 :echo](#214-echo)
     * [2.1.5 error messages](#215-error-messages)
-    * [2.1.6 in](#216-in)
-    * [2.1.7 modify](#217-modify)
-    * [2.1.8 required](#218-required)
-    * [2.1.9 validate](#219-validate)
+    * [2.1.6 :in](#216-in)
+    * [2.1.7 :modify](#217-modify)
+    * [2.1.8 :required](#218-required)
+    * [2.1.9 :validate](#219-validate)
   * [2.2 keypress](#22-keypress)
     * [2.2.1 :timeout](#221-timeout)
   * [2.3 multiline](#23-multiline)
@@ -81,19 +82,28 @@ Or install it yourself as:
     * [2.6.1 choices](#261-choices)
     * [2.6.1.1 :disabled](#2611-disabled)
     * [2.6.2 select](#262-select)
-      * [2.6.2.1 :per_page](#2621-per_page)
-      * [2.6.2.2 :disabled](#2622-disabled)
-      * [2.6.2.3 :filter](#2623-filter)
+      * [2.6.2.1 :cycle](#2621-cycle)
+      * [2.6.2.2 :enum](#2622-enum)
+      * [2.6.2.3 :help](#2623-help)
+      * [2.6.2.4 :marker](#2624-marker)
+      * [2.6.2.5 :per_page](#2625-per_page)
+      * [2.6.2.6 :disabled](#2626-disabled)
+      * [2.6.2.7 :filter](#2627-filter)
     * [2.6.3 multi_select](#263-multi_select)
-      * [2.6.3.1 :disabled](#2631-disabled)
-      * [2.6.3.2 :echo](#2632-echo)
-      * [2.6.3.3 :filter](#2633-filter)
-      * [2.6.3.4 :max](#2634-max)
+      * [2.6.3.1 :cycle](#2631-cycle)
+      * [2.6.3.2 :enum](#2632-enum)
+      * [2.6.3.3 :help](#2633-help)
+      * [2.6.3.4 :per_page](#2634-per_page)
+      * [2.6.3.5 :disabled](#2635-disabled)
+      * [2.6.3.6 :echo](#2636-echo)
+      * [2.6.3.7 :filter](#2637-filter)
+      * [2.6.3.8 :min](#2638-min)
+      * [2.6.3.9 :max](#2639-max)
     * [2.6.4 enum_select](#264-enum_select)
       * [2.6.4.1 :per_page](#2641-per_page)
       * [2.6.4.1 :disabled](#2641-disabled)
   * [2.7 expand](#27-expand)
-    * [2.7.1 auto_hint](#271-auto_hint)
+    * [2.7.1 :auto_hint](#271-auto_hint)
   * [2.8 collect](#28-collect)
   * [2.9 suggest](#29-suggest)
   * [2.10 slider](#210-slider)
@@ -105,31 +115,34 @@ Or install it yourself as:
 * [3. settings](#3-settings)
   * [3.1 :symbols](#31-symbols)
   * [3.2 :active_color](#32-active_color)
-  * [3.3 :enable_color](#33-enable-color)
+  * [3.3 :enable_color](#33-enable_color)
   * [3.4 :help_color](#34-help_color)
   * [3.5 :interrupt](#35-interrupt)
   * [3.6 :prefix](#36-prefix)
-  * [3.7 :track_history](#37-track_history)
+  * [3.7 :quiet](#37-quiet)
+  * [3.8 :track_history](#38-track_history)
 
 ## 1. Usage
 
 In order to start asking questions on the command line, create prompt:
 
 ```ruby
+require "tty-prompt"
+
 prompt = TTY::Prompt.new
 ```
 
 And then call `ask` with the question for simple input:
 
 ```ruby
-prompt.ask('What is your name?', default: ENV['USER'])
+prompt.ask("What is your name?", default: ENV["USER"])
 # => What is your name? (piotr)
 ```
 
 To confirm input use `yes?`:
 
 ```ruby
-prompt.yes?('Do you like Ruby?')
+prompt.yes?("Do you like Ruby?")
 # => Do you like Ruby? (Y/n)
 ```
 
@@ -184,13 +197,13 @@ 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 }
+  { 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)
+prompt.expand("Overwrite Gemfile?", choices)
 # =>
 # Overwrite Gemfile? (enter "h" for help) [y,n,a,d,q,h]
 ```
@@ -199,14 +212,14 @@ If you wish to collect more than one answer use `collect`:
 
 ```ruby
 result = prompt.collect do
-  key(:name).ask('Name?')
+  key(:name).ask("Name?")
 
-  key(:age).ask('Age?', convert: :int)
+  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/)
+    key(:street).ask("Street?", required: true)
+    key(:city).ask("City?")
+    key(:zip).ask("Zip?", validate: /\A\d{3}\Z/)
   end
 end
 # =>
@@ -233,25 +246,41 @@ prompt.ask("What is your name?") do |q|
 end
 ```
 
-#### 2.1.1 convert
+#### 2.1.1 `:convert`
 
 The `convert` property is used to convert input to a required type.
 
-By default no conversion is performed. The following conversions are provided:
+By default no conversion of input is performed. To change this use one of the following conversions:
 
-```ruby
-:bool       # true or false for strings such as "Yes", "No"
-:date       # date type
-:datetime   # datetime type
-:file       # File object
-:float      # decimal or error if cannot convert
-:int        # integer or error if cannot convert
-:path       # Pathname object
-:range      # range type
-:regexp     # regex expression
-:string     # string
-:symbol     # symbol
-```
+* `:boolean`|`:bool` - e.g. 'yes/1/y/t/' becomes `true`, 'no/0/n/f' becomes `false`
+* `:date` - parses dates formats "28/03/2020", "March 28th 2020"
+* `:time` - parses time formats "11:20:03"
+* `:float` - e.g. `-1` becomes `-1.0`
+* `:int`|`:integer` - e.g. `+1` becomes `1`
+* `:sym`|`:symbol` - e.g. "foo" becomes `:foo`
+* `:filepath` - converts to file path
+* `:path`|`:pathname` - converts to `Pathname` object
+* `:range` - e.g. '1-10' becomes `1..10` range object
+* `:regexp` - e.g. "foo|bar" becomes `/foo|bar/`
+* `:uri` - converts to `URI` object
+* `:list`|`:array` - e.g. 'a,b,c' becomes `["a", "b", "c"]`
+* `:map`|`:hash` - e.g. 'a:1 b:2 c:3' becomes `{a: "1", b: "2", c: "3"}`
+
+In addition you can specify a plural or append `list` or `array` to any base type:
+
+* `:ints` or `:int_list` - will convert to a list of integers
+* `:floats` or `:float_list` - will convert to a list of floats
+* `:bools` or `:bool_list` - will convert to a list of booleans, e.g. `t,f,t` becomes `[true, false, true]`
+
+Similarly, you can append `map` or `hash` to any base type:
+
+* `:int_map`|`:integer_map`|`:int_hash` - will convert to a hash of integers, e.g `a:1 b:2 c:3` becomes `{a: 1, b: 2, c: 3}`
+* `:bool_map` | `:boolean_map`|`:bool_hash` - will convert to a hash of booleans, e.g `a:t b:f c:t` becomes `{a: true, b: false, c: true}`
+
+By default, `map` converts keys to symbols, if you wish to use strings instead specify key type like so:
+
+* `:str_int_map` - will convert to a hash of string keys and integer values
+* `:string_integer_hash` - will convert to a hash of string keys and integer values
 
 For example, if you are interested in range type as answer do the following:
 
@@ -261,27 +290,54 @@ prompt.ask("Provide range of numbers?", convert: :range)
 # => 1..10
 ```
 
+If, on the other hand, you wish to convert input to a hash of integer values do:
+
+```ruby
+prompt.ask("Provide keys and values:", convert: :int_map)
+# Provide keys and values: a=1 b=2 c=3
+# => {a: 1, b: 2, c: 3}
+```
+
+If a user provides a wrong type for conversion an error message will be printed in the console:
+
+```ruby
+prompt.ask("Provide digit:", convert: :float)
+# Provide digit: x
+# >> Cannot convert `x` into 'float' type
+```
+
+You can further customize error message:
+
+```ruby
+prompt.ask("Provide digit:", convert: :float) do |q|
+  q.convert(:float, "Wrong value of %{value} for %{type} conversion")
+  # or
+  q.convert :float
+  q.messages[:convert?] = "Wrong value of %{value} for %{type} conversion"
+end
+```
+
 You can also provide a custom conversion like so:
 
 ```ruby
-prompt.ask('Ingredients? (comma sep list)') do |q|
+prompt.ask("Ingredients? (comma sep list)") do |q|
   q.convert -> (input) { input.split(/,\s*/) }
 end
 # Ingredients? (comma sep list) milk, eggs, flour
-# => ['milk', 'eggs', 'flour']
+# => ["milk", "eggs", "flour"]
 ```
 
-#### 2.1.2 default
+#### 2.1.2 `:default`
 
 The `:default` option is used if the user presses return key:
 
 ```ruby
-prompt.ask('What is your name?', default: 'Anonymous')
+prompt.ask("What is your name?", default: "Anonymous")
 # =>
 # What is your name? (Anonymous)
 ```
 
-#### 2.1.3 value
+#### 2.1.3 `:value`
 
 To pre-populate the input line for editing use `:value` option:
 
@@ -291,58 +347,58 @@ prompt.ask("What is your name?", value: "Piotr")
 # What is your name? Piotr
 ```
 
-#### 2.1.4 echo
+#### 2.1.4 `:echo`
 
 To control whether the input is shown back in terminal or not use `:echo` option like so:
 
 ```ruby
-prompt.ask('password:', echo: false)
+prompt.ask("password:", echo: false)
 ```
 
 #### 2.1.5 error messages
 
-By default `tty-prompt` comes with predefined error messages for `required`, `in`, `validate` options.
+By default `tty-prompt` comes with predefined error messages for `convert`, `required`, `in`, `validate` options.
 
 You can change these and configure to your liking either by passing message as second argument with the option:
 
 ```ruby
-prompt.ask('What is your email?') do |q|
-  q.validate(/\A\w+@\w+\.\w+\Z/, 'Invalid email address')
+prompt.ask("What is your email?") do |q|
+  q.validate(/\A\w+@\w+\.\w+\Z/, "Invalid email address")
 end
 ```
 
-Or change the `messages` key entry out of `:required?`, `:valid?`, `:range?`:
+Or change the `messages` key entry out of `:convert?`, `:range?`, `:required?` and `:valid?`:
 
 ```ruby
-prompt.ask('What is your email?') do |q|
+prompt.ask("What is your email?") do |q|
   q.validate(/\A\w+@\w+\.\w+\Z/)
-  q.messages[:valid?] = 'Invalid email address'
+  q.messages[:valid?] = "Invalid email address"
 end
 ```
 
 To change default range validation error message do:
 
 ```ruby
-prompt.ask('How spicy on scale (1-5)? ') do |q|
-  q.in '1-5'
-  q.messages[:range?] = '%{value} out of expected range #{in}'
+prompt.ask("How spicy on scale (1-5)? ") do |q|
+  q.in "1-5"
+  q.messages[:range?] = "%{value} out of expected range %{in}"
 end
 ```
 
-#### 2.1.6 in
+#### 2.1.6 `:in`
 
 In order to check that provided input falls inside a range of inputs use the `in` option. For example, if we wanted to ask a user for a single digit in given range we may do following:
 
 ```ruby
-ask("Provide number in range: 0-9?") { |q| q.in('0-9') }
+prompt.ask("Provide number in range: 0-9?") { |q| q.in("0-9") }
 ```
 
-#### 2.1.7 modify
+#### 2.1.7 `:modify`
 
 Set the `:modify` option if you want to handle whitespace or letter capitalization.
 
 ```ruby
-prompt.ask('Enter text:') do |q|
+prompt.ask("Enter text:") do |q|
   q.modify :strip, :collapse
 end
 ```
@@ -355,14 +411,16 @@ Available letter casing settings are:
 ```
 
 Available whitespace settings are:
+
 ```ruby
 :trim     # remove whitespace from both ends of the input
+:strip    # same as :trim
 :chomp    # remove whitespace at the end of input
 :collapse # reduce all whitespace to single character
 :remove   # remove all whitespace
 ```
 
-#### 2.1.8 required
+#### 2.1.8 `:required`
 
 To ensure that input is provided use `:required` option:
 
@@ -372,20 +430,47 @@ prompt.ask("What's your phone number?", required: true)
 # >> Value must be provided
 ```
 
-#### 2.1.9 validate
+#### 2.1.9 `:validate`
+
+In order to validate that input matches a given pattern you can pass the `validate` option/method.
+
+Validate accepts `Regex`, `Proc` or `Symbol`.
+
+```ruby
+prompt.ask("What is your username?") do |q|
+  q.validate(/\A[^.]+\.[^.]+\Z/)
+end
+```
+
+The above can also be expressed as a `Proc`:
+
+```ruby
+prompt.ask("What is your username?") do |q|
+  q.validate ->(input) { input =~ /\A[^.]+\.[^.]+\Z/ }
+end
+```
+
+There is a built-in validation for `:email` and you can use it directly like so:
+
+```ruby
+prompt.ask("What is your email?") { |q| q.validate :email }
+```
 
-In order to validate that input matches a given patter you can pass the `validate` option. Validate setting accepts `Regex`, `Proc` or `Symbol`.
+The default validation message is `"Your answer is invalid (must match %{valid})"` and you can customise it by passing in a second argument:
 
 ```ruby
-prompt.ask('What is your username?') do |q|
-  q.validate /^[^\.]+\.[^\.]+/
+prompt.ask("What is your username?") do |q|
+  q.validate(/\A[^.]+\.[^.]+\Z/, "Invalid username: %{value}, must match %{valid}")
 end
 ```
 
-The **TTY::Prompt** comes with built-in validations for `:email` and you can use them directly like so:
+The default message can also be set using `messages` and the `:valid?` key:
 
-```prompt
-prompt.ask('What is your email?') { |q| q.validate :email }
+```ruby
+prompt.ask("What is your username?") do |q|
+  q.validate(/\A[^.]+\.[^.]+\Z/)
+  q.messages[:valid?] = "Invalid username: %{value}, must match %{valid}")
+end
 ```
 
 ### 2.2. keypress
@@ -428,21 +513,22 @@ prompt.multiline("Description?")
 # 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"]
+# =>
+# ["I know not all that may be coming,\n", "but be it what it will,\n", "I'll go to it laughing.\n"]
 ```
 
 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.')
+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'
+  q.default "A super sweet prompt."
+  q.help "Press thy ctrl+d to end"
 end
 ```
 
@@ -451,28 +537,28 @@ end
 If you require input of confidential information use `mask` method. By default each character that is printed is replaced by `•` symbol. All configuration options applicable to `ask` method can be used with `mask` as well.
 
 ```ruby
-prompt.mask('What is your secret?')
+prompt.mask("What is your secret?")
 # => What is your secret? ••••
 ```
 
-The masking character can be changed by passing `:symbols` option with `:mask` key:
+The masking character can be changed by passing the `:mask` key:
 
 ```ruby
-heart = prompt.decorate(prompt.symbols[:heart] + ' ', :magenta)
-prompt.mask('What is your secret?', symbols: {mask: heart})
+heart = prompt.decorate(prompt.symbols[:heart] + " ", :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:
 
 ```ruby
-prompt.mask('What is your secret?', echo: false)
+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|
+prompt.mask("What is your secret?", mask: heart) do |q|
   q.validate(/[a-z\ ]{5,15}/)
 end
 ```
@@ -482,7 +568,7 @@ end
 In order to display a query asking for boolean input from user use `yes?` like so:
 
 ```ruby
-prompt.yes?('Do you like Ruby?')
+prompt.yes?("Do you like Ruby?")
 # =>
 # Do you like Ruby? (Y/n)
 ```
@@ -493,7 +579,7 @@ It's enough to provide the `suffix` option for the prompt to accept matching ans
 
 ```ruby
 prompt.yes?("Are you a human?") do |q|
-  q.suffix 'Yup/nope'
+  q.suffix "Yup/nope"
 end
 # =>
 # Are you a human? (Yup/nope)
@@ -504,8 +590,8 @@ Alternatively, instead of `suffix` option provide the `positive` and `negative`
 ```ruby
 prompt.yes?("Are you a human?") do |q|
   q.default false
-  q.positive 'Yup'
-  q.negative 'Nope'
+  q.positive "Yup"
+  q.negative "Nope"
 end
 # =>
 # Are you a human? (yup/Nope)
@@ -514,10 +600,10 @@ end
 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'
+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
 # =>
@@ -527,7 +613,7 @@ end
 There is also the opposite for asking confirmation of negative question:
 
 ```ruby
-prompt.no?('Do you hate Ruby?')
+prompt.no?("Do you hate Ruby?")
 # =>
 # Do you hate Ruby? (y/N)
 ```
@@ -548,15 +634,21 @@ By default the choice name is also the value the prompt will return when selecte
 
 ```ruby
 choices = {small: 1, medium: 2, large: 3}
+prompt.select("What size?", choices)
+# =>
+# What size? (Press ↑/↓ arrow to move and Enter to select)
+# ‣ small
+#   medium
+#   large
 ```
 
 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 individual choices:
 
 ```ruby
 choices = [
-  {name: 'small', value: 1},
-  {name: 'medium', value: 2, disabled: '(out of stock)'},
-  {name: 'large', value: 3}
+  {name: "small", value: 1},
+  {name: "medium", value: 2, disabled: "(out of stock)"},
+  {name: "large", value: 3}
 ]
 ```
 
@@ -565,20 +657,25 @@ You can specify `:key` as an additional option which will be used as short name
 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
+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
+# =>
+# What size? (Press ↑/↓ arrow to move and Enter to select)
+# ‣ small
+# ✘ medium (out of stock)
+#   large
 ```
 
 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
+prompt.select("What size?") do |menu|
+  menu.choice "small", 1
+  menu.choice "medium", 2, disabled: "(out of stock)"
+  menu.choice "large", 3
 end
 ```
 
@@ -588,9 +685,9 @@ The `:disabled` key indicates to display a choice as currently unavailable to se
 
 ```ruby
 choices = [
-  {name: 'small', value: 1},
-  {name: 'medium', value: 2, disabled: '(out of stock)'}
-  {name: 'large', value: 3}
+  {name: "small", value: 1},
+  {name: "medium", value: 2, disabled: "(out of stock)"},
+  {name: "large", value: 3}
 ]
 ```
 
@@ -611,9 +708,9 @@ You can also provide options through DSL using the `choice` method for single en
 
 ```ruby
 prompt.select("Choose your destiny?") do |menu|
-  menu.choice 'Scorpion'
-  menu.choice 'Kano'
-  menu.choice 'Jax'
+  menu.choice "Scorpion"
+  menu.choice "Kano"
+  menu.choice "Jax"
 end
 # =>
 # Choose your destiny? (Use ↑/↓ arrow keys, press Enter to select)
@@ -626,9 +723,9 @@ By default the choice name is used as return value, but you can provide your cus
 
 ```ruby
 prompt.select("Choose your destiny?") do |menu|
-  menu.choice 'Scorpion', 1
-  menu.choice 'Kano', 2
-  menu.choice 'Jax', -> { 'Nice choice captain!' }
+  menu.choice "Scorpion", 1
+  menu.choice "Kano", 2
+  menu.choice "Jax", -> { "Nice choice captain!" }
 end
 # =>
 # Choose your destiny? (Use ↑/↓ arrow keys, press Enter to select)
@@ -640,19 +737,20 @@ end
 If you wish you can also provide a simple hash to denote choice name and its value like so:
 
 ```ruby
-choices = {'Scorpion' => 1, 'Kano' => 2, 'Jax' => 3}
+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`:
+To mark particular answer as selected use `default` with either an index of the choice starting from `1` or a choice's name:
 
 ```ruby
 prompt.select("Choose your destiny?") do |menu|
   menu.default 3
+  # or menu.default "Jax"
 
-  menu.choice 'Scorpion', 1
-  menu.choice 'Kano', 2
-  menu.choice 'Jax', 3
+  menu.choice "Scorpion", 1
+  menu.choice "Kano", 2
+  menu.choice "Jax", 3
 end
 # =>
 # Choose your destiny? (Use ↑/↓ arrow keys, press Enter to select)
@@ -661,7 +759,9 @@ end
 # ‣ Jax
 ```
 
-You can navigate the choices using the arrow keys or define your own key mappings (see [keyboard events](#212-keyboard-events). When reaching the top/bottom of the list, the selection does not cycle around by default. If you wish to enable cycling, you can pass `cycle: true` to `select` and `mutli_select`:
+#### 2.6.2.1 `:cycle`
+
+You can navigate the choices using the arrow keys or define your own key mappings (see [keyboard events](#212-keyboard-events). When reaching the top/bottom of the list, the selection does not cycle around by default. If you wish to enable cycling, you can pass `cycle: true` to `select` and `multi_select`:
 
 ```ruby
 prompt.select("Choose your destiny?", %w(Scorpion Kano Jax), cycle: true)
@@ -672,15 +772,17 @@ prompt.select("Choose your destiny?", %w(Scorpion Kano Jax), cycle: true)
 #   Jax
 ```
 
+#### 2.6.2.2 `:enum`
+
 For ordered choices set `enum` to any delimiter String. In that way, you can use arrows keys and numbers (0-9) to select the item.
 
 ```ruby
 prompt.select("Choose your destiny?") do |menu|
-  menu.enum '.'
+  menu.enum "."
 
-  menu.choice 'Scorpion', 1
-  menu.choice 'Kano', 2
-  menu.choice 'Jax', 3
+  menu.choice "Scorpion", 1
+  menu.choice "Kano", 2
+  menu.choice "Jax", 3
 end
 # =>
 # Choose your destiny? (Use ↑/↓ arrow or number (0-9) keys, press Enter to select)
@@ -689,24 +791,40 @@ end
 # ‣ 3. Jax
 ```
 
-You can configure help message and/or marker like so
+#### 2.6.2.3 `:help`
+
+You can configure help message with `:help` and when to display it with `:show_help` options. The help can be displayed on `start`, `never` or `always`:
+
+```ruby
+choices = %w(Scorpion Kano Jax)
+prompt.select("Choose your destiny?", choices, help: "(Bash keyboard keys)", show_help: :always)
+# =>
+# Choose your destiny? (Bash keyboard keys)
+# > Scorpion
+#   Kano
+#   Jax
+```
+
+#### 2.6.2.4 `:marker`
+
+You can configure active marker like so:
 
 ```ruby
 choices = %w(Scorpion Kano Jax)
-prompt.select("Choose your destiny?", choices, help: "(Bash keyboard)", symbols: {marker: '>'})
+prompt.select("Choose your destiny?", choices, symbols: { marker: ">" })
 # =>
-# Choose your destiny? (Bash keyboard)
+# Choose your destiny? (Use ↑/↓ and ←/→ arrow keys, press Enter to select)
 # > Scorpion
 #   Kano
 #   Jax
 ```
 
-#### 2.6.1.1 `:per_page`
+#### 2.6.2.5 `:per_page`
 
 By default the menu is paginated if selection grows beyond `6` items. To change this setting use `:per_page` configuration.
 
 ```ruby
-letters = ('A'..'Z').to_a
+letters = ("A".."Z").to_a
 prompt.select("Choose your letter?", letters, per_page: 4)
 # =>
 # Which letter? (Use ↑/↓ and ←/→ arrow keys, press Enter to select)
@@ -716,35 +834,41 @@ prompt.select("Choose your letter?", letters, per_page: 4)
 #   D
 ```
 
-You can also customise page navigation text using `:page_help` option:
+You can also customise page navigation text using `:help` option:
 ```ruby
-letters = ('A'..'Z').to_a
+letters = ("A".."Z").to_a
 prompt.select("Choose your letter?") do |menu|
   menu.per_page 4
-  menu.page_help '(Wiggle thy finger up or down to see more)'
+  menu.help "(Wiggle thy finger up/down and left/right to see more)"
   menu.choices letters
 end
+# =>
+# Which letter? (Wiggle thy finger up/down and left/right to see more)
+# ‣ A
+#   B
+#   C
+#   D
 ```
 
-#### 2.6.2.2 `:disabled`
+#### 2.6.2.6 `: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'
+  "Scorpion",
+  "Kano",
+  { name: "Goro", disabled: "(injury)" },
+  "Jax",
+  "Kitana",
+  "Raiden"
 ]
 ```
 
 The disabled choice will be displayed with a cross `✘` character next to it and followed by an explanation:
 
 ```ruby
-prompt.select('Choose your destiny?', warriors)
+prompt.select("Choose your destiny?", warriors)
 # =>
 # Choose your destiny? (Use ↑/↓ arrow keys, press Enter to select)
 # ‣ Scorpion
@@ -755,13 +879,13 @@ prompt.select('Choose your destiny?', warriors)
 #   Raiden
 ```
 
-#### 2.6.2.3 `:filter`
+#### 2.6.2.7 `: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)
+prompt.select("Choose your destiny?", warriors, filter: true)
 # =>
 # Choose your destiny? (Use ↑/↓ arrow keys, press Enter to select, and letter keys to filter)
 # ‣ Scorpion
@@ -830,11 +954,12 @@ prompt.multi_select("Select drinks?") do |menu|
 end
 ```
 
-To mark choice(s) as selected use the `default` option with index(s) of the option(s) starting from `1`:
+To mark choice(s) as selected use the `default` option with either index(s) of the choice(s) starting from `1` or choice name(s):
 
 ```ruby
 prompt.multi_select("Select drinks?") do |menu|
   menu.default 2, 5
+  # or menu.default :beer, :whisky
 
   menu.choice :vodka,   {score: 10}
   menu.choice :beer,    {score: 20}
@@ -851,11 +976,21 @@ end
 # ‣ ⬢ bourbon
 ```
 
+#### 2.6.3.1 `:cycle`
+
+Also like, `select`, the method takes an option `cycle` (which defaults to `false`), which lets you configure whether the selection should cycle around when reaching the top/bottom of the list when navigating:
+
+```ruby
+prompt.multi_select("Select drinks?", %w(vodka beer wine), cycle: true)
+```
+
+#### 2.6.3.2 `:enum`
+
 Like `select`, for ordered choices set `enum` to any delimiter String. In that way, you can use arrows keys and numbers (0-9) to select the item.
 
 ```ruby
 prompt.multi_select("Select drinks?") do |menu|
-  menu.enum ')'
+  menu.enum ")"
 
   menu.choice :vodka,   {score: 10}
   menu.choice :beer,    {score: 20}
@@ -879,17 +1014,13 @@ And when you press enter you will see the following selected:
 # => [{score: 20}, {score: 50}]
 ```
 
-Also like, `select`, the method takes an option `cycle` (which defaults to `false`), which lets you configure whether the selection should cycle around when reaching the top/bottom of the list when navigating:
+#### 2.6.3.3 `:help`
 
-```ruby
-prompt.multi_select("Select drinks?", %w(vodka beer wine), cycle: true)
-```
-
-You can configure help message and/or marker like so
+You can configure help message with `:help` and when to display it with `:show_help` options. The help can be displayed on `start`, `never` or `always`:
 
 ```ruby
 choices = {vodka: 1, beer: 2, wine: 3, whisky: 4, bourbon: 5}
-prompt.multi_select("Select drinks?", choices, help: 'Press beer can against keyboard')
+prompt.multi_select("Select drinks?", choices, help: "Press beer can against keyboard", show_help: :always)
 # =>
 # Select drinks? (Press beer can against keyboard)"
 # ‣ ⬡ vodka
@@ -899,10 +1030,12 @@ prompt.multi_select("Select drinks?", choices, help: 'Press beer can against key
 #   ⬡ bourbon
 ```
 
+#### 2.6.3.4 `:per_page`
+
 By default the menu is paginated if selection grows beyond `6` items. To change this setting use `:per_page` configuration.
 
 ```ruby
-letters = ('A'..'Z').to_a
+letters = ("A".."Z").to_a
 prompt.multi_select("Choose your letter?", letters, per_page: 4)
 # =>
 # Which letter? (Use ↑/↓ and ←/→ arrow keys, press Space to select and Enter to finish)
@@ -912,25 +1045,25 @@ prompt.multi_select("Choose your letter?", letters, per_page: 4)
 #   ⬡ D
 ```
 
-#### 2.6.3.1 `:disabled`
+#### 2.6.3.5 `: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 drinks, the sake and beer are currently out of stock:
 
 ```ruby
 drinks = [
-  'bourbon',
-  {name: 'sake', disabled: '(out of stock)'},
-  'vodka',
-  {name: 'beer', disabled: '(out of stock)'},
-  'wine',
-  'whisky'
+  "bourbon",
+  {name: "sake", disabled: "(out of stock)"},
+  "vodka",
+  {name: "beer", disabled: "(out of stock)"},
+  "wine",
+  "whisky"
 ]
 ```
 
 The disabled choice will be displayed with a cross `✘` character next to it and followed by an explanation:
 
 ```ruby
-prompt.multi_select('Choose your favourite drink?', drinks)
+prompt.multi_select("Choose your favourite drink?", drinks)
 # =>
 # Choose your favourite drink? (Use ↑/↓ arrow keys, press Space to select and Enter to finish)
 # ‣ ⬡ bourbon
@@ -941,7 +1074,7 @@ prompt.multi_select('Choose your favourite drink?', drinks)
 #   ⬡ whisky
 ```
 
-#### 2.6.3.2 `:echo`
+#### 2.6.3.6 `:echo`
 
 To control whether the selected items are shown on the question
 header use the :echo option:
@@ -958,7 +1091,7 @@ prompt.multi_select("Select drinks?", choices, echo: false)
 # ‣ ⬢ 5) bourbon
 ```
 
-#### 2.6.3.3 `:filter`
+#### 2.6.3.7 `:filter`
 
 To activate dynamic list filtering on letter/number typing, use the :filter option:
 
@@ -988,9 +1121,25 @@ If the user changes or deletes a filter, the choices previously selected remain
 
 The `filter` option is not compatible with `enum`.
 
-#### 2.6.3.4 `:max`
+#### 2.6.3.8 `:min`
+
+To force the minimum number of choices an user must select, use the `:min` option:
+
+```ruby
+choices = %w(vodka beer wine whisky bourbon)
+prompt.multi_select("Select drinks?", choices, min: 3)
+# =>
+# Select drinks? (min. 3) vodka, beer
+#   ⬢ vodka
+#   ⬢ beer
+#   ⬡ wine
+#   ⬡ wiskey
+# ‣ ⬡ bourbon
+```
+
+#### 2.6.3.9 `:max`
 
-To limit the number of choices an user can select, use `:max` option:
+To limit the number of choices an user can select, use the `:max` option:
 
 ```ruby
 choices = %w(vodka beer wine whisky bourbon)
@@ -1010,7 +1159,7 @@ In order to ask for standard selection from indexed list you can use `enum_selec
 
 ```ruby
 choices = %w(emacs nano vim)
-prompt.enum_select("Select an editor?")
+prompt.enum_select("Select an editor?", choices)
 # =>
 #
 # Select an editor?
@@ -1025,9 +1174,9 @@ Similar to `select` and `multi_select`, you can provide question options through
 ```ruby
 choices = %w(nano vim emacs)
 prompt.enum_select("Select an editor?") do |menu|
-  menu.choice :nano,  '/bin/nano'
-  menu.choice :vim,   '/usr/bin/vim'
-  menu.choice :emacs, '/usr/bin/emacs'
+  menu.choice :nano,  "/bin/nano"
+  menu.choice :vim,   "/usr/bin/vim"
+  menu.choice :emacs, "/usr/bin/emacs"
 end
 # =>
 #
@@ -1040,17 +1189,18 @@ end
 # Select an editor? /bin/nano
 ```
 
-You can change the indexed numbers by passing `enum` option and the default option by using `default` like so
+You can change the indexed numbers formatting by passing `enum` option. The `default` option lets you specify which choice to mark as selected by default. It accepts an index of the choice starting from `1` or a choice name:
 
 ```ruby
 choices = %w(nano vim emacs)
 prompt.enum_select("Select an editor?") do |menu|
   menu.default 2
-  menu.enum '.'
+  # or menu.defualt "/usr/bin/vim"
+  menu.enum "."
 
-  menu.choice :nano,  '/bin/nano'
-  menu.choice :vim,   '/usr/bin/vim'
-  menu.choice :emacs, '/usr/bin/emacs'
+  menu.choice :nano,  "/bin/nano"
+  menu.choice :vim,   "/usr/bin/vim"
+  menu.choice :emacs, "/usr/bin/emacs"
 end
 # =>
 #
@@ -1068,7 +1218,7 @@ end
 By default the menu is paginated if selection grows beyond `6` items. To change this setting use `:per_page` configuration.
 
 ```ruby
-letters = ('A'..'Z').to_a
+letters = ("A".."Z").to_a
 prompt.enum_select("Choose your letter?", letters, per_page: 4)
 # =>
 # Which letter?
@@ -1086,10 +1236,10 @@ To make a choice unavailable use the `:disabled` option and, if you wish, as val
 
 ```ruby
 choices = [
-  {name: "Emacs", disabled: '(not installed)'},
+  {name: "Emacs", disabled: "(not installed)"},
   "Atom",
   "GNU nano",
-  {name: "Notepad++", disabled: '(not installed)'},
+  {name: "Notepad++", disabled: "(not installed)"},
   "Sublime",
   "Vim"
 ]
@@ -1099,7 +1249,7 @@ The disabled choice will be displayed with a cross ✘ character next to it and
 
 
 ```ruby
-prompt.enum_select('Select an editor', choices)
+prompt.enum_select("Select an editor", choices)
 # =>
 # Select an editor
 # ✘ 1) Emacs (not installed)
@@ -1120,16 +1270,16 @@ As first argument `expand` takes the message to display and as a second an array
 ```ruby
 choices = [
   {
-    key: 'y',
-    name: 'overwrite this file',
+    key: "y",
+    name: "overwrite this file",
     value: :yes
   }, {
-    key: 'n',
-    name: 'do not overwrite this file',
+    key: "n",
+    name: "do not overwrite this file",
     value: :no
   }, {
-    key: 'q',
-    name: 'quit; do not overwrite this file ',
+    key: "q",
+    name: "quit; do not overwrite this file ",
     value: :quit
   }
 ]
@@ -1138,19 +1288,19 @@ choices = [
 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
+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)
+prompt.expand("Overwrite Gemfile?", choices)
 # =>
 # Overwrite Gemfile? (enter "h" for help) [y,n,q,h]
 ```
@@ -1180,7 +1330,7 @@ Run `examples/expand.rb` to see the prompt in action.
 To show hint by default use `:auto_hint` option:
 
 ```ruby
-prompt.expand('Overwrite Gemfile?', choices, auto_hint: true)
+prompt.expand("Overwrite Gemfile?", choices, auto_hint: true)
 # =>
 # Overwrite Gemfile? (enter "h" for help) [y,n,q,h]
 # >> overwrite this file
@@ -1194,14 +1344,14 @@ For example to gather some contact information do:
 
 ```ruby
 prompt.collect do
-  key(:name).ask('Name?')
+  key(:name).ask("Name?")
 
-  key(:age).ask('Age?', convert: :int)
+  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/)
+    key(:street).ask("Street?", required: true)
+    key(:city).ask("City?")
+    key(:zip).ask("Zip?", validate: /\A\d{3}\Z/)
   end
 end
 # =>
@@ -1210,17 +1360,17 @@ end
 
 In order to collect _mutliple values_ for a given key in a loop, chain `values` onto the `key` desired:
 
-```rb
+```ruby
 result = prompt.collect do
-  key(:name).ask('Name?')
+  key(:name).ask("Name?")
 
-  key(:age).ask('Age?', convert: :int)
+  key(:age).ask("Age?", convert: :int)
 
   while prompt.yes?("continue?")
     key(:addresses).values do
-      key(:street).ask('Street?', required: true)
-      key(:city).ask('City?')
-      key(:zip).ask('Zip?', validate: /\A\d{3}\Z/)
+      key(:street).ask("Street?", required: true)
+      key(:city).ask("City?")
+      key(:zip).ask("Zip?", validate: /\A\d{3}\Z/)
     end
   end
 end
@@ -1240,7 +1390,7 @@ end
 To suggest possible matches for the user input use `suggest` method like so:
 
 ```ruby
-prompt.suggest('sta', ['stage', 'stash', 'commit', 'branch'])
+prompt.suggest("sta", ["stage", "stash", "commit", "branch"])
 # =>
 # Did you mean one of these?
 #         stage
@@ -1251,7 +1401,7 @@ To customize query text presented pass `:single_text` and `:plural_text` options
 
 ```ruby
 possible = %w(status stage stash commit branch blame)
-prompt.suggest('b', possible, indent: 4, single_text: 'Perhaps you meant?')
+prompt.suggest("b", possible, indent: 4, single_text: "Perhaps you meant?")
 # =>
 # Perhaps you meant?
 #     blame
@@ -1259,33 +1409,51 @@ prompt.suggest('b', possible, indent: 4, single_text: 'Perhaps you meant?')
 
 ### 2.10 slider
 
-If you have constrained range of numbers for user to choose from you may consider using `slider`.
+If you'd rather not display all possible values in a vertical list, you may consider using `slider`. The slider provides easy visual way of picking a value marked by `●` symbol.
 
-The slider provides easy visual way of picking a value marked by `●` symbol. You can set `:min`(defaults to 0), `:max` and `:step`(defaults to 1) options to configure slider range:
+For integers, you can set `:min`(defaults to 0), `:max` and `:step`(defaults to 1) options to configure slider range:
 
 ```ruby
-prompt.slider('Volume', max: 100, step: 5)
+prompt.slider("Volume", min: 0, max: 100, step: 5)
 # =>
 # Volume ──────────●────────── 50
-# (Use arrow keys, press Enter to select)
+# (Use ←/→ arrow keys, press Enter to select)
+```
+
+For everything else, you can provide an array of your desired choices:
+
+```ruby
+prompt.slider("Letter", ('a'..'z').to_a)
+# =>
+# Letter ────────────●───────────── m
+# (Use ←/→ arrow keys, press Enter to select)
 ```
 
 By default the slider is configured to pick middle of the range as a start value, you can change this by using the `:default` option:
 
 ```ruby
-prompt.slider('Volume', max: 100, step: 5, default: 75)
+prompt.slider("Volume", max: 100, step: 5, default: 75)
 # =>
 # Volume ───────────────●────── 75
-# (Use arrow keys, press Enter to select)
+# (Use ←/→ arrow keys, press Enter to select)
+```
+
+You can also select the default value by name:
+
+```ruby
+prompt.slider("Letter", ('a'..'z').to_a, default: 'q')
+# =>
+# Letter ──────────────────●─────── q
+# (Use ←/→ arrow keys, press Enter to select)
 ```
 
 You can also change the default slider formatting using the `:format`. The value must contain the `:slider` token to show current value and any `sprintf` compatible flag for number display, in our case `%d`:
 
 ```ruby
-prompt.slider('Volume', max: 100, step: 5, default: 75, format: "|:slider| %d%")
+prompt.slider("Volume", max: 100, step: 5, default: 75, format: "|:slider| %d%%")
 # =>
 # Volume |───────────────●──────| 75%
-# (Use arrow keys, press Enter to select)
+# (Use ←/→ arrow keys, press Enter to select)
 ```
 
 You can also specify slider range with decimal numbers. For example, to have a step of `0.5` and display each value with a single decimal place use `%f` as format:
@@ -1294,32 +1462,63 @@ You can also specify slider range with decimal numbers. For example, to have a s
 prompt.slider("Volume", max: 10, step: 0.5, default: 5, format: "|:slider| %.1f")
 # =>
 # Volume |───────────────●──────| 7.5
-# (Use arrow keys, press Enter to select)
+# (Use ←/→ arrow keys, press Enter to select)
+```
+
+You can alternatively provide a proc/lambda to customize your formatting even further:
+
+```ruby
+slider_format = -> (slider, value) { "|#{slider}| #{value.zero? ? "muted" : "%.1f"}" % value }
+prompt.slider("Volume", max: 10, step: 0.5, default: 0, format: slider_format)
+# =>
+# Volume |●─────────────────────| muted
+# (Use ←/→ arrow keys, press Enter to select)
 ```
 
 If you wish to change the slider handle and the slider range display use `:symbols` option:
 
 ```ruby
-prompt.slider("Volume", max: 100, step: 5, default: 75, symbols: {bullet: 'x', line: '_'})
+prompt.slider("Volume", max: 100, step: 5, default: 75, symbols: {bullet: "x", line: "_"})
 # =>
 # Volume _______________x______ 75%
-# (Use arrow keys, press Enter to select)
+# (Use ←/→ arrow keys, press Enter to select)
+```
+
+You can configure help message with `:help` and when to display with `:show_help` options. The help can be displayed on `start`, `never` or `always`:
+
+```ruby
+prompt.slider("Volume", max: 10, default: 7, help: "(Move arrows left and right to set value)", show_help: :always)
+# =>
+# Volume ───────────────●────── 7
+# (Move arrows left and right to set value)
 ```
 
 Slider can be configured through DSL as well:
 
 ```ruby
-prompt.slider('What size?') do |range|
+prompt.slider("What size?") do |range|
   range.max 100
   range.step 5
   range.default 75
-  range.format "|:slider| %d%"
+  range.format "|:slider| %d%%"
 end
 # =>
 # Volume |───────────────●──────| 75%
-# (Use arrow keys, press Enter to select)
+# (Use ←/→ arrow keys, press Enter to select)
 ```
 
+```ruby
+prompt.slider("What letter?") do |range|
+  range.choices ('a'..'z').to_a
+  range.format "|:slider| %s"
+  range.default 'q'
+end
+# =>
+# What letter? |──────────────────●───────| q
+# (Use ←/→ arrow keys, press Enter to select)
+```
+
+
 ### 2.11 say
 
 To simply print message out to standard output use `say` like so:
@@ -1375,11 +1574,11 @@ For example, to add vim like key navigation to `select` prompt one would do the
 
 ```ruby
 prompt.on(:keypress) do |event|
-  if event.value == 'j'
+  if event.value == "j"
     prompt.trigger(:keydown)
   end
 
-  if event.value == 'k'
+  if event.value == "k"
     prompt.trigger(:keyup)
   end
 end
@@ -1415,7 +1614,7 @@ The available events are:
 Many prompts use symbols to display information. You can overwrite the default symbols for all the prompts using the `:symbols` key and hash of symbol names as value:
 
 ```ruby
-prompt = TTY::Prompt.new(symbols: {marker: '>'})
+prompt = TTY::Prompt.new(symbols: {marker: ">"})
 ```
 
 The following symbols can be overwritten:
@@ -1437,16 +1636,37 @@ The following symbols can be overwritten:
 
 ### 3.2 `: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 globally for all prompts or individually.
+All prompt types support `:active_color` option. By default it's set to `:green` value.
+
+The `select`, `multi_select`, `enum_select` and `expand` prompts use the active color to highlight the currently selected choice.
+
+The answer provided by the user is also highlighted with the active color.
+
+This `:active_color` as value accepts either a color symbol or callable object.
+
+For example, to change all prompts active color to `:cyan` do:
 
 ```ruby
 prompt = TTY::Prompt.new(active_color: :cyan)
 ```
 
-or per individual input do:
+You could also use `pastel`:
 
 ```ruby
-prompt.select('What size?', %w(Large Medium Small), active_color: :cyan)
+notice = Pastel.new.cyan.on_blue.detach
+prompt = TTY::Prompt.new(active_color: notice)
+````
+
+Or use coloring of your own choice:
+
+```
+prompt = TTY::Prompt.new(active_color: ->(str) { my-color-gem(str) })
+```
+
+This option can be applied either globally 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.
@@ -1456,29 +1676,50 @@ Please [see pastel](https://github.com/piotrmurach/pastel#3-supported-colors) fo
 If you wish to disable coloring for a prompt simply pass `:enable_color` option
 
 ```ruby
-prompt = TTY::Prompt.new(enable_color: true)
+prompt = TTY::Prompt.new(enable_color: false)
 ```
 
 ### 3.4 `: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 globally for all prompts or individually.
+The `:help_color` option is used to customize the display color for all the help text. By default it's set to `:bright_black` value.
+
+Prompts such as `select`, `multi_select`, `expand` support `:help_color`. This option can be applied either globally for all prompts or individually.
+
+The `:help_color` option as value accepts either a color symbol or callable object.
+
+For example, to change all prompts help color to `:cyan` do:
 
 ```ruby
 prompt = TTY::Prompt.new(help_color: :cyan)
 ```
 
-or per individual input do:
+You could also use `pastel`:
 
 ```ruby
-prompt.select('What size?', %w(Large Medium Small), help_color: :cyan)
+notice = Pastel.new.cyan.on_blue.detach
+prompt = TTY::Prompt.new(help_color: notice)
+````
+
+Or use coloring of your own choice:
+
+```ruby
+prompt = TTY::Prompt.new(help_color: ->(str) { my-color-gem(str) })
 ```
 
+Or configure `:help_color` for an individual prompt:
+
+```ruby
+prompt.select("What size?", %w(Large Medium Small), help_color: :cyan)
+```
+
+Please [see pastel](https://github.com/piotrmurach/pastel#3-supported-colors) for all supported colors.
+
 ### 3.5 `:interrupt`
 
 By default `InputInterrupt` error will be raised when the user hits the interrupt key(Control-C). However, you can customise this behaviour by passing the `:interrupt` option. The available options are:
 
 * `:signal` - sends interrupt signal
-* `:exit` - exists with status code
+* `:exit` - exits with status code
 * `:noop` - skips handler
 * custom proc
 
@@ -1493,10 +1734,21 @@ prompt = TTY::Prompt.new(interrupt: :signal)
 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: '[?] ')
+prompt = TTY::Prompt.new(prefix: "[?] ")
 ```
 
-### 3.7 `:track_history`
+### 3.7 `:quiet`
+
+Prompts such as `select`, `multi_select`, `expand`, `slider` support `:quiet` which is used to disable re-echoing of the question and answer after selection is done. This option can be applied either globally for all prompts or individually.
+
+```ruby
+# global
+prompt = TTY::Prompt.new(quiet: true)
+# single prompt
+prompt.select("What is your favorite color?", %w(blue yellow orange))
+````
+
+### 3.8 `: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 previous or next lines when user presses up/down arrows respectively. However, if you wish to disable this behaviour use `:track_history` option like so: