austb-tty-prompt 0.13.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 00d9b66e9648c7cbead34f0012a6120d5789b476
+  data.tar.gz: 0effaa17428ccaee0ede5627c0857cb1d1d58823
+SHA512:
+  metadata.gz: 2f07c871bce4d4dc2e6797d586b518616c7ceb3836402de240d6b631b049b58caa09444d9b20f9bf973a02e5a24ddc789f75d423edc560b972dafecb01405c1e
+  data.tar.gz: 3d092541ec166c171f9cb473b9e35cb6d532c29bdfd204ff9982c5afe13ef14620b97eca569771b585bb1fbdba4f6ecd37cd42a38ef11864441af056ecc84ddd

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--require spec_helper
+--warnings

data/.travis.yml

@@ -0,0 +1,25 @@
+---
+language: ruby
+sudo: false
+cache: bundler
+bundler_args: --without tools
+script: "bundle exec rake ci"
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.10
+  - 2.2.6
+  - 2.3.3
+  - 2.4.1
+  - ruby-head
+  - jruby-9000
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head
+  fast_finish: true
+branches:
+  only: master
+notifications:
+  email: false

data/CHANGELOG.md

@@ -0,0 +1,218 @@
+# Change log
+
+## [v0.13.0] _ 2017-xx-xx
+
+### Added
+
+### Changed
+* Change Timeout to use clock time instead of sleep to measure interval
+
+### Fixed
+* Fix keypress with timeout option to cleanly stop timeout thread
+* Fix Reader to treat git-bash & cygwin emulators as unix like
+
+## [v0.12.0] - 2017-03-19
+
+### Added
+* Add Multiline question type
+* Add Keypress question type
+* Add Reader::History for storing buffered lines
+* Add Reader::Line for line abstraction
+
+### Changed
+* Remove :read option from Question
+* Chnage Reader#read_line to handle raw mode for processing special
+  characters such as Ctrl+x, navigate through history buffer
+  using up/down arrows, allow editing current line by moving left/right
+  with arrow keys and inserting content
+* Change Reader#read_multiline to gather multi line input correctly,
+  skip empty lines and terminate when Ctrl+d and Ctrl+z are pressed
+* Change Reader::Mode to check if tty is available by Matt Martyn (@MMartyn)
+* Change #keypress prompt to correctly refresh line and accept :keys & :timeout options
+
+### Fixed
+* Fix issue with #select, #multi_selct, #enum_select when choices are
+  provided as hash object together with prompt options.
+* Fix issue with default parameter for yes?/no? prompt by Carlos Fonseca (@carlosefonseca)
+* Fix List#help to allow setting help text through DSL
+
+## [v0.11.0] - 2017-02-26
+
+### Added
+* Add Console for reading input characters on Unix systems
+* Add WinConsole for reading input characters on Windows systems
+* Add WindowsApi to allow for calls to external Windows api
+* Add echo support to multilist by Keith Keith T. Garner(@ktgeek)
+
+### Changed
+* Change Reader to use Console for input reading
+* Change Codes to use codepoints instead of strings
+* Change Reader#read_line to match #gets behaviour
+* Change Symbols to provide Unicode support on windows
+* Change Slider to display Unicode when possible
+* Change ConverterRegistry to be immutable
+* Change Reader to expose #trigger in place of #publish for events firing
+
+### Fixed
+* Fix `modify` throwing exception, when user enters empty input by Igor Rzegocki(@ajgon)
+* Fix #clear_line behaviour by using tty-cursor 0.4.0 to work in all terminals
+* Fix paging issue for lists shorter than :per_page value repeating title
+* Fix #mask prompt to correctly match input on Windows
+* Fix @mask to use default error messages
+* Fix #select & #multi_select prompts to allow changing options with arrow keys on Windows
+* Fix #echo to work correctly in zsh shell by štef(@d4be4st)
+* Fix Slider#keyright event accepting max value outside of range
+* Fix 2.4.0 conversion errors by using necromancer 0.4.0
+* Fix #enum_select preventing selection of first item
+
+## [v0.10.1] - 2017-02-06
+
+### Fixed
+* Fix File namespacing
+
+## [v0.10.0] - 2017-01-01
+
+### Added
+* Add :enable_color option for toggling colors support
+
+### Changed
+* Update pastel dependency version
+
+## [v0.9.0] - 2016-12-20
+
+### Added
+* Add ability to paginate choices list for #select, #multi_select & #enum_select
+  with :per_page, :page_info and :default options
+* Add ability to switch through options in #select & #multi_select using the tab key
+
+### Fixed
+* Fix readers to accept multibyte characters reported by Jaehyun Shin(@keepcosmos)
+
+## [v0.8.0] - 2016-11-29
+
+### Added
+* Add ability to publish custom key events for VIM keybindings customisations etc...
+
+### Fixed
+* Fix Reader#read_char to use Ruby internal buffers instead of direct system call by @kke(Kimmo Lehto)
+* Fix issue with #ask required & validate checks to take into account required when validating values
+* Fix bug with #read_keypress to handle function keys and meta navigation keys
+* Fix issue with default messages not displaying for `range`, `required` and `validate`
+
+## [v0.7.1] - 2016-08-07
+
+### Fixed
+* Fix Reader::Mode to include standard io library
+
+## [v0.7.0] - 2016-07-17
+
+### Added
+* Add :interrupt_handler option to customise keyboard interrupt behaviour
+
+### Changed
+* Remove tty-platform dependency
+
+### Fixed
+* Fix Reader#read_keypress issue when handling interrupt signal by Ondrej Moravcik(@ondra-m)
+* Fix raw & echo modes to use standard library support by Kim Burgestrand(@Burgestrand)
+
+## [v0.6.0] - 2016-05-21
+
+### Changed
+* Upgrade tty-cursor dependency
+
+### Fixed
+* Fix issue with reader trapping signals by @kylekyle
+* Fix expand to use new prev_line implementation
+
+## [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
+* Add :enum option for #select & #multi_select to allow for numerical selection by @rtoshiro
+* Add new key event types to KeyEvent
+* Add #slider for picking values from range of numbers
+* Add #enum_select for selecting option from enumerated list
+* Add ability to configure error messages for #ask call
+* Add new ConversionError type
+
+### Changed
+* Move #blank? to Utils
+* Update pastel dependency
+
+## [v0.3.0] - 2015-12-28
+
+### Added
+* Add prefix option to prompt to customize #ask, #select, #multi_select
+* Add default printing to #ask
+* Add #yes?/#no? boolean queries
+* Add Evaluator and Result for validation checking to Question
+* Add ability for #ask to display error messages on failed validation
+* Add ability to specify in-built names for validation e.i. :email
+* Add KeyEvent for keyboard events publishing to Reader
+* Add #read_multiline to Reader
+* Add :convert option for ask configuration
+* Add ability to specify custom proc converters
+* Add #ask_keypress to gather character input
+* Add #ask_multiline to gather multiline input
+* Add MaskedQuestion & #mask method for masking input stream characters
+
+### Changed
+* Change Reader#read_keypress to be robust and read correctly byte sequences
+* Change Reader#getc to #read_line and extend arguments with echo option
+* Extract cursor movement to dependency tty-cursor
+* Change List & MultiList to subscribe to keyboard events
+* Change to move mode inside reader namespace
+* Remove Response & Error objects
+* Remove :char option from #ask
+* Change :read option to specify mode of reading out of :line, :multiline, :keypress
+* Rename #confirm to #ok
+
+## [v0.2.0] - 2015-11-23
+
+### Added
+* Add ability to select choice form list #select
+* Add ability to select multiple options #multi_select
+* Add :read option to #ask for reading specific type input
+
+### Changed
+* Change #ask api to be similar to #select and #multi_select behaviour
+* Change #ask :argument option to be :required
+* Remove :valid option from #ask as #select is a better solution
+
+## [v0.1.0] - 2015-11-01
+
+* Initial implementation and release
+
+[v0.12.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.11.0...v0.12.0
+[v0.11.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.10.1...v0.11.0
+[v0.10.1]: https://github.com/piotrmurach/tty-prompt/compare/v0.10.0...v0.10.1
+[v0.10.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.9.0...v0.10.0
+[v0.9.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.8.0...v0.9.0
+[v0.8.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.7.1...v0.8.0
+[v0.7.1]: https://github.com/piotrmurach/tty-prompt/compare/v0.7.0...v0.7.1
+[v0.7.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.6.0...v0.7.0
+[v0.6.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.5.0...v0.6.0
+[v0.5.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.4.0...v0.5.0
+[v0.4.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.3.0...v0.4.0
+[v0.3.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.2.0...v0.3.0
+[v0.2.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.1.0...v0.2.0
+[v0.1.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.1.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at [email]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,19 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'benchmark-ips', '~> 2.0.0'
+  gem 'simplecov', '~> 0.10.0'
+  gem 'coveralls', '~> 0.8.2'
+  gem 'term-ansicolor', '=1.3.2'
+end
+
+group :tools do
+  gem 'byebug', platform: :mri
+end
+
+group :metrics do
+  gem 'yard',      '~> 0.8.7'
+  gem 'yardstick', '~> 0.9.9'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Piotr Murach
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,1132 @@
+# 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]
+[![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]
+[![Inline docs](http://inch-ci.org/github/piotrmurach/tty-prompt.svg?branch=master)][inchpages]
+
+[gitter]: https://gitter.im/piotrmurach/tty
+[gem]: http://badge.fury.io/rb/tty-prompt
+[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
+[coverage]: https://coveralls.io/github/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/piotrmurach/tty) toolkit.
+
+## Features
+
+* Number of prompt types for gathering user input
+* A robust API for validating complex inputs
+* User friendly error feedback
+* Intuitive DSL for creating complex menus
+* Ability to page long menus
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tty-prompt'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install tty-prompt
+
+## Contents
+
+* [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 echo](#213-echo)
+    * [2.1.4 error messages](#214-error-messages)
+    * [2.1.5 in](#215-in)
+    * [2.1.6 modify](#216-modify)
+    * [2.1.7 required](#217-required)
+    * [2.1.8 validate](#218-validate)
+  * [2.2 keypress](#22-keypress)
+    * [2.2.1 timeout](#221-timeout)
+  * [2.3 multiline](#23-multiline)
+  * [2.4 mask](#24-mask)
+  * [2.5 yes?/no?](#25-yesno)
+  * [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.3 enum_select](#263-enum_select)
+  * [2.7 expand](#27-expand)
+  * [2.8 collect](#28-collect)
+  * [2.9 suggest](#29-suggest)
+  * [2.10 slider](#210-slider)
+  * [2.11 say](#211-say)
+    * [2.11.1 ok](#2111-ok)
+    * [2.11.2 warn](#2112-warn)
+    * [2.11.3 error](#2113-error)
+  * [2.12 keyboard events](#212-keyboard-events)
+* [3. settings](#3-settings)
+  * [3.1 active_color](#31-active_color)
+  * [3.2 enable_color](#32-enable-color)
+  * [3.3 help_color](#33-help_color)
+  * [3.4 interrupt](#34-interrupt)
+  * [3.5 prefix](#35-prefix)
+  * [3.6 trakc_history](#36-track_history)
+
+## 1. Usage
+
+In order to start asking questions on the command line, create prompt:
+
+```ruby
+prompt = TTY::Prompt.new
+```
+
+and then call `ask` with the question for simple input:
+
+```ruby
+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?')
+# => Do you like Ruby? (Y/n)
+```
+
+If you want to input password or secret information use `mask`:
+
+```ruby
+prompt.mask("What is your secret?")
+# => What is your secret? ••••
+```
+
+Asking question with list of options couldn't be easier using `select` like so:
+
+```ruby
+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.multi_select("Select drinks?", choices)
+# =>
+#
+# Select drinks? (Use arrow keys, press Space to select and Enter to finish)"
+# ‣ ⬡ vodka
+#   ⬡ beer
+#   ⬡ wine
+#   ⬡ whisky
+#   ⬡ bourbon
+```
+
+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?", choices)
+# =>
+#
+# Select an editor?
+#   1) emacs
+#   2) nano
+#   3) vim
+#   Choose 1-3 [1]:
+```
+
+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
+
+In order to ask a basic question do:
+
+```ruby
+prompt.ask("What is your name?")
+```
+
+However, to prompt for more complex input you can use robust API by passing hash of properties or using a block like so:
+
+```ruby
+prompt.ask("What is your name?") do |q|
+  q.required true
+  q.validate /\A\w+\Z/
+  q.modify   :capitalize
+end
+```
+
+#### 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:
+
+```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
+```
+
+For example, if you are interested in range type as answer do the following:
+
+```ruby
+prompt.ask("Provide range of numbers?", convert: :range)
+# Provide range of numbers? 1-10
+# => 1..10
+```
+
+You can also provide a custom conversion like so:
+
+```ruby
+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']
+```
+
+#### 2.1.2 default
+
+The `:default` option is used if the user presses return key:
+
+```ruby
+prompt.ask('What is your name?', default: 'Anonymous')
+# =>
+# What is your name? (Anonymous)
+```
+
+#### 2.1.3 echo
+
+To control whether the input is shown back in terminal or not use `:echo` option like so:
+
+```ruby
+prompt.ask('password:', echo: false)
+```
+
+#### 2.1.4 error messages
+
+By default `tty-prompt` comes with predefined error messages for `required`, `in`, `validate` options.
+
+You can change these and configure to your liking either by inling them with the option:
+
+```ruby
+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?`:
+
+```ruby
+prompt.ask('What is your email?') do |q|
+  q.validate(/\A\w+@\w+\.\w+\Z/)
+  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}'
+end
+```
+
+#### 2.1.5 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') }
+```
+
+#### 2.1.6 modify
+
+Set the `:modify` option if you want to handle whitespace or letter capitalization.
+
+```ruby
+prompt.ask('Enter text:') do |q|
+  q.modify :strip, :collapse
+end
+```
+
+Available letter casing settings are:
+```ruby
+:up         # change to upper case
+:down       # change to small case
+:capitalize # capitalize each word
+```
+
+Available whitespace settings are:
+```ruby
+:trim     # remove whitespace from both ends of the input
+:chomp    # remove whitespace at the end of input
+:collapse # reduce all whitespace to single character
+:remove   # remove all whitespace
+```
+
+#### 2.1.7 required
+
+To ensure that input is provided use `:required` option:
+
+```ruby
+prompt.ask("What's your phone number?", required: true)
+# What's your phone number?
+# >> Value must be provided
+```
+
+#### 2.1.8 validate
+
+In order to validate that input matches a given patter you can pass the `validate` option. Validate setting accepts `Regex`, `Proc` or `Symbol`.
+
+```ruby
+prompt.ask('What is your username?') do |q|
+  q.validate /^[^\.]+\.[^\.]+/
+end
+```
+
+The **TTY::Prompt** comes with bult-in validations for `:email` and you can use them directly like so:
+
+```prompt
+prompt.ask('What is your email?') { |q| q.validate :email }
+```
+
+### 2.2. keypress
+
+In order to ask question that awaits a single character answer use `keypress` prompt like so:
+
+```ruby
+prompt.keypress("Press key ?")
+# Press key?
+# => a
+```
+
+By default any key is accepted but you can limit keys by using `:keys` option. Any key event names such as `:space` or `:ctrl_k` are valid:
+
+```ruby
+prompt.keypress("Press space or enter to continue, keys: [:space, :return])
+```
+
+#### 2.2.1 timeout
+
+Timeout can be set using `:timeout` option to expire prompt and allow the script to continue automatically:
+
+```ruby
+prompt.keypress("Press any key to continue, resumes automatically in 3 seconds ...", timeout: 3)
+```
+
+In addition the `keypress` recognises `:countdown` token when inserted inside the question. It will automatically countdown the time in seconds:
+
+```ruby
+prompt.keypress("Press any key to continue, resumes automatically in :countdown ...", timeout: 3)
+```
+
+### 2.3 multiline
+
+Asking for multiline input can be done with `multiline` method. The reading of input will terminate when `Ctrl+d` or `Ctrl+z` is pressed. Empty lines will not be included in the returned array.
+
+```ruby
+prompt.multiline("Description?")
+# Description? (Press CTRL-D or CTRL-Z to finish)
+# I know not all that may be coming,
+# but be it what it will,
+# I'll go to it laughing.
+# => ["I know not all that may be coming,\n", "but be it what it will,\n", "I'll go to it laughing.\n"]
+```
+
+The `multiline` uses similar options to those supported by `ask` prompt. For example, to provide default description:
+
+```ruby
+prompt.multiline("Description?", default: 'A super sweet prompt.')
+```
+
+or using DSL:
+
+```ruby
+prompt.multiline("Description?") do |q|
+  q.default 'A super sweet prompt.'
+  q.help 'Press thy ctrl+d to end'
+end
+```
+
+### 2.4 mask
+
+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?')
+# => What is your secret? ••••
+```
+
+The masking character can be changed by passing `:mask` option:
+
+```ruby
+heart = prompt.decorate('❤ ', :magenta)
+prompt.mask('What is your secret?', mask: heart)
+# => What is your secret? ❤  ❤  ❤  ❤  ❤ 
+```
+
+If you don't wish to show any output use `:echo` option like so:
+
+```ruby
+prompt.mask('What is your secret?', echo: false)
+```
+
+You can also provide validation for your mask to enforce for instance strong passwords:
+
+```ruby
+prompt.mask('What is your secret?', mask: heart) do |q|
+  q.validate(/[a-z\ ]{5,15}/)
+end
+```
+
+### 2.5 yes?/no?
+
+In order to display a query asking for boolean input from user use `yes?` like so:
+
+```ruby
+prompt.yes?('Do you like Ruby?')
+# =>
+# Do you like Ruby? (Y/n)
+```
+
+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.yes?("Are you a human?") do |q|
+  q.suffix 'Yup/nope'
+end
+# =>
+# Are you a human? (Yup/nope)
+```
+
+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?')
+# =>
+# Do you hate Ruby? (y/N)
+```
+
+Similarly to `yes?` method, you can supply the same options to customize the question.
+
+### 2.6 menu
+
+### 2.6.1 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` 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 including a `Proc` object:
+
+```ruby
+prompt.select("Choose your destiny?") do |menu|
+  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)
+# ‣ Scorpion
+#   Kano
+#   Jax
+```
+
+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}
+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
+```
+
+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.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)
+#   1. Scorpion
+#   2. Kano
+# ‣ 3. Jax
+```
+
+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)", marker: '>')
+# =>
+# Choose your destiny? (Bash keyboard)
+# > Scorpion
+#   Kano
+#   Jax
+```
+
+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
+prompt.select("Choose your letter?", letters, per_page: 4)
+# =>
+# Which letter? (Use arrow keys, press Enter to select)
+# ‣ A
+#   B
+#   C
+#   D
+# (Move up or down to reveal more choices)
+```
+
+You can also customise page navigation text using `:page_help` option:
+```ruby
+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.choices letters
+end
+```
+
+### 2.6.2 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.multi_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.multi_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
+```
+
+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.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
+#   ⬡ 1) vodka
+#   ⬢ 2) beer
+#   ⬡ 3) wine
+#   ⬡ 4) whisky
+# ‣ ⬢ 5) bourbon
+```
+
+And when you press enter you will see the following selected:
+
+```ruby
+# Select drinks? beer, bourbon
+# => [{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.multi_select("Select drinks?", choices, help: 'Press beer can against keyboard')
+# =>
+# Select drinks? (Press beer can against keyboard)"
+# ‣ ⬡ vodka
+#   ⬡ beer
+#   ⬡ wine
+#   ⬡ whisky
+#   ⬡ bourbon
+```
+
+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
+prompt.multi_select("Choose your letter?", letters, per_page: 4)
+# =>
+# Which letter? (Use arrow keys, press Space to select and Enter to finish)
+# ‣ ⬡ A
+#   ⬡ B
+#   ⬡ C
+#   ⬡ D
+# (Move up or down to reveal more choices)
+```
+
+### 2.6.2.1 echo
+
+To control whether the selected items are shown on the question
+header use the :echo option:
+
+```ruby
+choices = %w(vodka beer wine whisky bourbon)
+prompt.multi_select("Select drinks?", choices, echo: false)
+# =>
+# Select drinks?
+#   ⬡ vodka
+#   ⬢ 2) beer
+#   ⬡ 3) wine
+#   ⬡ 4) whisky
+# ‣ ⬢ 5) bourbon
+```
+
+### 2.6.3 enum_select
+
+In order to ask for standard selection from indexed list you can use `enum_select` and pass question together with possible choices:
+
+```ruby
+choices = %w(emacs nano vim)
+prompt.enum_select("Select an editor?")
+# =>
+#
+# Select an editor?
+#   1) nano
+#   2) vim
+#   3) emacs
+#   Choose 1-3 [1]:
+```
+
+Similar to `select` and `multi_select`, you can provide question options through DSL using `choice` method and/or `choices` like so:
+
+```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'
+end
+# =>
+#
+# Select an editor?
+#   1) nano
+#   2) vim
+#   3) emacs
+#   Choose 1-3 [1]:
+#
+# Select an editor? /bin/nano
+```
+
+You can change the indexed numbers by passing `enum` option and the default option by using `default` like so
+
+```ruby
+choices = %w(nano vim emacs)
+prompt.enum_select("Select an editor?") do |menu|
+  menu.default 2
+  menu.enum '.'
+
+  menu.choice :nano,  '/bin/nano'
+  menu.choice :vim,   '/usr/bin/vim'
+  menu.choice :emacs, '/usr/bin/emacs'
+end
+# =>
+#
+# Select an editor?
+#   1. nano
+#   2. vim
+#   3. emacs
+#   Choose 1-3 [2]:
+#
+# Select an editor? /usr/bin/vim
+```
+
+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
+prompt.enum_select("Choose your letter?", letters, per_page: 4)
+# =>
+# Which letter?
+#   1) A
+#   2) B
+#   3) C
+#   4) D
+#   Choose 1-26 [1]:
+# (Press tab/right or left to reveal more choices)
+```
+
+### 2.7 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.8 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.9 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
+```
+
+To customize query text presented pass `:single_text` and `:plural_text` options to respectively change the message when one match is found or many.
+
+```ruby
+possible = %w(status stage stash commit branch blame)
+prompt.suggest('b', possible, indent: 4, single_text: 'Perhaps you meant?')
+# =>
+# Perhaps you meant?
+#     blame
+```
+
+### 2.10 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.
+
+```ruby
+prompt.slider('What size?', min: 32, max: 54, step: 2)
+# =>
+#
+# What size? (User arrow keys, press Enter to select)
+# |------O-----| 44
+```
+
+Slider can be configured through DSL as well:
+
+```ruby
+prompt.slider('What size?') do |range|
+  range.default 4
+  range.min 0
+  range.max 20
+  range.step 2
+end
+# =>
+#
+# What size? (User arrow keys, press Enter to select)
+# |--O-------| 4
+```
+
+### 2.11 say
+
+To simply print message out to stdout use `say` like so:
+
+```ruby
+prompt.say(...)
+```
+
+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.11.1 ok
+
+Print message(s) in green do:
+
+```ruby
+prompt.ok(...)
+```
+
+#### 2.12.2 warn
+
+Print message(s) in yellow do:
+
+```ruby
+prompt.warn(...)
+```
+
+#### 2.11.3 error
+
+Print message(s) in red do:
+
+```ruby
+prompt.error(...)
+```
+
+#### 2.12 keyboard events
+
+All the prompt types, when a key is pressed, fire key press events. You can subscribe to listen to this events by calling `on` with type of event name.
+
+```ruby
+prompt.on(:keypress) { |event| ... }
+```
+
+The event object is yielded to a block whenever particular event fires. The event has `key` and `value` methods. Further, the `key` responds to following messages:
+
+* `name`  - the name of the event such as :up, :down, letter or digit
+* `meta`  - true if event is non-standard key associated
+* `shift` - true if shift has been pressed with the key
+* `ctrl`  - true if ctrl has been pressed with the key
+
+For example, to add vim like key navigation to `select` prompt one would do the following:
+
+```ruby
+prompt.on(:keypress) do |event|
+  if event.value == 'j'
+    prompt.trigger(:keydown)
+  end
+
+  if event.value == 'k'
+    prompt.trigger(:keyup)
+  end
+end
+```
+
+You can subscribe to more than one event:
+
+```ruby
+prompt.on(:keypress) { |key| ... }
+      .on(:keydown)  { |key| ... }
+```
+
+The available events are:
+
+* `:keypress`
+* `:keydown`
+* `:keyup`
+* `:keyleft`
+* `:keyright`
+* `:keynum`
+* `:keytab`
+* `:keyenter`
+* `:keyreturn`
+* `:keyspace`
+* `:keyescape`
+* `:keydelete`
+* `:keybackspace`
+
+## 3 settings
+
+### 3.1 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 = TTY::Prompt.new(active_color: :cyan)
+```
+
+or per individual input do:
+
+```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.
+
+### 3.2 enable_color
+
+If you wish to disable coloring for a prompt simply pass `:enable_color` option
+
+```
+prompt = TTY::Prompt.new(enable_color: true)
+```
+
+### 3.3 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 = TTY::Prompt.new(help_color: :cyan)
+```
+
+or per individual input do:
+
+```ruby
+prompt.select('What size?', %w(Large Medium Small), help_color: :cyan)
+```
+
+### 3.4 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
+* `:noop` - skips handler
+* custom proc
+
+For example, to send interrupt signal do:
+
+```ruby
+prompt = TTY::Prompt.new(interrupt: :signal)
+```
+
+### 3.5 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: '[?] ')
+```
+
+### 3.6 track_history
+
+The prompts that accept line input such as `multiline` or `ask` provide history buffer that tracks all the lines entered during `TTY::Prompt.new` interactions. The history buffer provides previoius or next lines when user presses up/down arrows respectively. However, if you wish to disable this behaviour use `:track_history` option like so:
+
+```ruby
+prompt = TTY::Prompt.new(track_history: false)
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/piotrmurach/tty-prompt/fork )
+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`)
+5. Create a new Pull Request
+
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## Copyright
+
+Copyright (c) 2015-2017 Piotr Murach. See LICENSE for further details.