tty-prompt 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5e24965d09c08a3bf136438bad66551d05f25a0f
-  data.tar.gz: 476702a67dd13fe4796c888d089107f4b6f7f18d
+  metadata.gz: a6c43cfd17fb7fe5d5f256f124571fb904a3d6b3
+  data.tar.gz: 0cc290a7c31157fe9d953133ce2f7a3df5042142
 SHA512:
-  metadata.gz: 0645bb40ca7b847976e69d0d3c65e4e0a9441f4e3bade6ef1e0d38e7d9ef28e66132645aa30740c7a258939fe262664ed93306968eb76969bee768029d19c406
-  data.tar.gz: 70c03c2eb72010d0efe7d8a125c285dc32ec34117e29e2a44b17839c645a8b1650dd14d1184b7b8a871dc92b2c44121ab1e727aa9f5ca41c893184b678171fc8
+  metadata.gz: b20f2aa8fab1798c62b8e5a9770351ab58fcf6de0afbbf7a60eba88c31e0b551273cd706944a3e17e3b6e1f6f1366d5e0d60f8c61b638c28dc6e9f0b657b9aac
+  data.tar.gz: 6f2be862205c779ba31d2651b4e9d7874d5df4a4566218e0793224215db197900dc930022940418f04fb7427948036928897e7384f65570f5d741f05b7f405e8

data/.travis.yml

@@ -1,4 +1,7 @@
+---
 language: ruby
+sudo: false
+cache: bundler
 bundler_args: --without yard benchmarks
 script: "bundle exec rake ci"
 rvm:
@@ -7,13 +10,13 @@ rvm:
   - 2.1
   - 2.2
   - ruby-head
+  - jruby-19mode
+  - jruby
+  - rbx-2
+env:
+  global:
+    - JRUBY_OPTS="-Xcli.debug=true --debug"
 matrix:
-  include:
-    - rvm: jruby-19mode
-    - rvm: jruby-20mode
-    - rvm: jruby-21mode
-    - rvm: jruby-head
-    - rvm: rbx-2
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head

data/CHANGELOG.md

@@ -1,12 +1,49 @@
-0.2.0 (Nov 23, 2015)
+# Change log
 
+## [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
-* Add :read option to #ask for reading specific type input
 * Remove :valid option from #ask as #select is a better solution
 
-0.1.0 (Nov 1, 2015)
+## [v0.1.0] - 2015-11-01
 
 * Initial implementation and release
+
+[v0.3.0]: https://github.com/peter-murach/tty-prompt/compare/v0.2.0...v0.3.0
+[v0.2.0]: https://github.com/peter-murach/tty-prompt/compare/v0.1.0...v0.2.0
+[v0.1.0]: https://github.com/peter-murach/tty-prompt/compare/v0.1.0

data/Gemfile

@@ -3,7 +3,6 @@ source 'https://rubygems.org'
 gemspec
 
 group :development do
-  gem 'rake',  '~> 10.4.2'
   gem 'rspec', '~> 3.3.0'
   gem 'yard',  '~> 0.8.7'
   gem 'benchmark-ips', '~> 2.0.0'

data/README.md

@@ -41,12 +41,25 @@ Or install it yourself as:
 * [1. Usage](#1-usage)
 * [2. Interface](#2-interface)
   * [2.1 ask](#21-ask)
-    * [2.1.1 settings](#211-settings)
-    * [2.1.2 valid read keywords](#212-valid-read-keywords)
-  * [2.2 select](#22-select)
-  * [2.3 multi_select](#23-multi_select)
-  * [2.4 say](#25-say)
-  * [2.5 suggest](#26-suggest)
+  * [2.2 settings](#22-settings)
+    * [2.2.1 convert](#221-convert)
+    * [2.2.2 default](#222-default)
+    * [2.2.3 echo](#223-echo)
+    * [2.2.4 in](#224-in)
+    * [2.2.5 modify](#225-modify)
+    * [2.2.6 required](#226-required)
+    * [2.2.7 validate](#227-validate)
+  * [2.3 keypress](#23-keypress)
+  * [2.4 multiline](#24-multiline)
+  * [2.5 mask](#25-mask)
+  * [2.6 yes?/no?](#26-yesno)
+  * [2.7 select](#27-select)
+  * [2.8 multi_select](#28-multi_select)
+  * [2.9 suggest](#29-suggest)
+  * [2.10 say](#210-say)
+  * [2.11 ok](#211-ok)
+  * [2.12 warn](#212-warn)
+  * [2.13 error](#213-warn)
 
 ## 1. Usage
 
@@ -59,7 +72,22 @@ prompt = TTY::Prompt.new
 and then call `ask` with the question for simple input:
 
 ```ruby
-prompt.ask('Do you like Ruby?', type: :bool) # => true
+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:
@@ -92,13 +120,13 @@ prompt.select("Select drinks?", choices)
 
 ### 2.1 ask
 
-In order to ask a basic question with a string answer do:
+In order to ask a basic question do:
 
 ```ruby
-answer = prompt.ask("What is your name?")
+prompt.ask("What is your name?")
 ```
 
-In order to prompt for more complex input you can use robust API by passing hash of properties or using block:
+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|
@@ -108,66 +136,199 @@ prompt.ask("What is your name?") do |q|
 end
 ```
 
-#### 2.1.1 settings
+### 2.2 settings
 
-Below is a list of the settings that may be used for customizing `ask` method behaviour:
+Below is a list of the settings that may be used for customizing `ask`, `mask`, `multiline`, `keypress` methods behaviour:
 
 ```ruby
-char       # turn character based input, otherwise line (default: false)
-default    # default value used if none is provided
-echo       # turn echo on and off (default: true)
-in         # specify range '0-9', '0..9', '0...9' or negative '-1..-9'
-mask       # mask characters i.e '****' (default: false)
-modify     # apply answer modification :upcase, :downcase, :trim, :chomp etc..
-read       # Specifies the type of input such as :bool, :string [see](#211-valid-read-keywords)
-required   # If true, value entered must be non-empty (default: false)
-validate   # regex, proc against which stdin input is checked
+:convert    # conversion applied to input such as :bool or proc
+:default    # default value used if none is provided
+:echo       # turn echo on and off (default: true)
+:in         # specify range '0-9', '0..9', '0...9' or negative '-1..-9'
+:modify     # apply answer modification :upcase, :downcase, :trim, :chomp etc..
+:required   # If true, value entered must be non-empty (default: false)
+:validate   # regex, proc against which input is checked
 ```
 
-Validate setting can take `Regex`, `Proc` like so:
+#### 2.2.1 convert
 
-```ruby
-prompt.ask('What is your username?') { |q|
-  q.validate { |input| input =~ (/^[^\.]+\.[^\.]+/) }
-}
-```
-
-For example, if we wanted to ask a user for a single digit in given range
-
-```ruby
-ask("Provide number in range: 0-9") { |q| q.in('0-9') }
-```
-
-#### 2.1.2 valid read keywords
-
-The most common thing to do is to cast the answer to specific type. The `read` property is used for that. By default `:string` answer is assumed but this can be changed using one of the following custom readers:
+ 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"
-:char       # first character
 :date       # date type
 :datetime   # datetime type
-:email      # validate answer against email regex
-:file       # a File object
+:file       # File object
 :float      # decimal or error if cannot convert
 :int        # integer or error if cannot convert
-:multiline  # multiple line string
-:password   # string with echo turned off
+:path       # Pathname object
 :range      # range type
-:regex      # regex expression
+:regexp     # regex expression
 :string     # string
 :symbol     # symbol
-:text       # multiline string
-:keypress   # the key pressed
 ```
 
 For example, if you are interested in range type as answer do the following:
 
 ```ruby
-ask("Provide range of numbers?", read: :range)
+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.2.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.2.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.2.4 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.2.5 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 small case
+:down       # change to upper 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.2.6 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?
+# >> No value provided for required
+```
+
+#### 2.2.7 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.3 keypress
+
+In order to ask question with a single character or keypress answer use `ask_keypress`:
+
+```ruby
+prompt.ask_keypress("Which one do you prefer a, b, c or d ?")
 ```
 
-### 2.2 select
+### 2.4 multiline
+
+Asking for multiline input can be done with `ask_multiline` method.
+
+```ruby
+prompt.ask_multiline("Provide description?")
+```
+
+The reading of input will terminate when empty line is submitted.
+
+
+### 2.5 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
+prompt.mask('What is your secret?', mask: '\u2665')
+# => 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)
+```
+
+### 2.6 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)
+```
+
+the same can be achieved by using plain `ask`:
+
+```ruby
+prompt.ask('Do you like Ruby? (Y/n)', convert: :bool)
+```
+
+There is also the opposite for asking confirmation of negative option:
+
+```ruby
+prompt.no?('Do you hate Ruby?')
+# =>
+# Do you like Ruby? (y/N)
+```
+
+### 2.7 select
 
 For asking questions involving list of options use `select` method by passing the question and possible choices:
 
@@ -246,7 +407,7 @@ prompt.select("Choose your destiny?", choices, help: "(Bash keyboard)")
 #   Jax
 ```
 
-### 2.3 multi_select
+### 2.8 multi_select
 
 For asking questions involving multiple selection list use `multi_select` method by passing the question and possible choices:
 
@@ -312,23 +473,7 @@ And when you press enter you will see the following selected:
 # => [{score: 20}, {score: 50}]
 ```
 
-### 2.4 say
-
-To simply print message out to stdout use `say` like so:
-
-```ruby
-prompt.say(...)          # print message to stdout
-```
-
-**TTY::Prompt** provides more specific versions of `say` method to better express intenation behind the message:
-
-```ruby
-prompt.confirm      # print message(s) in green
-prompt.warn         # print message(s) in yellow
-prompt.error        # print message(s) in red
-```
-
-### 2.5 suggest
+### 2.9 suggest
 
 To suggest possible matches for the user input use `suggest` method like so:
 
@@ -350,6 +495,42 @@ prompt.suggest('b', possible, indent: 4, single_text: 'Perhaps you meant?')
 #     blame
 ```
 
+### 2.10 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/peter-murach/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 ok
+
+Print message(s) in green do:
+
+```ruby
+prompt.ok(...)
+```
+
+### 2.12 warn
+
+Print message(s) in yellow do:
+
+```ruby
+prompt.warn(...)
+```
+
+### 2.13 error
+
+Print message(s) in red do:
+
+```ruby
+prompt.error(...)
+```
+
 ## Contributing
 
 1. Fork it ( https://github.com/peter-murach/tty-prompt/fork )