tty-prompt 0.19.0 → 0.23.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +81 -0
- data/LICENSE.txt +1 -1
- data/README.md +485 -233
- data/lib/tty-prompt.rb +1 -2
- data/lib/tty/prompt.rb +159 -147
- data/lib/tty/prompt/answers_collector.rb +5 -5
- data/lib/tty/prompt/block_paginator.rb +1 -1
- data/lib/tty/prompt/choice.rb +31 -13
- data/lib/tty/prompt/choices.rb +30 -12
- data/lib/tty/prompt/confirm_question.rb +42 -16
- data/lib/tty/prompt/const.rb +17 -0
- data/lib/tty/prompt/converter_dsl.rb +6 -7
- data/lib/tty/prompt/converter_registry.rb +31 -26
- data/lib/tty/prompt/converters.rb +139 -32
- data/lib/tty/prompt/enum_list.rb +58 -25
- data/lib/tty/prompt/errors.rb +31 -0
- data/lib/tty/prompt/evaluator.rb +2 -2
- data/lib/tty/prompt/expander.rb +27 -15
- data/lib/tty/prompt/keypress.rb +5 -3
- data/lib/tty/prompt/list.rb +101 -38
- data/lib/tty/prompt/mask_question.rb +9 -5
- data/lib/tty/prompt/multi_list.rb +108 -29
- data/lib/tty/prompt/multiline.rb +9 -7
- data/lib/tty/prompt/paginator.rb +1 -1
- data/lib/tty/prompt/question.rb +67 -36
- data/lib/tty/prompt/question/checks.rb +20 -2
- data/lib/tty/prompt/question/modifier.rb +4 -2
- data/lib/tty/prompt/question/validation.rb +3 -3
- data/lib/tty/prompt/selected_choices.rb +77 -0
- data/lib/tty/prompt/slider.rb +110 -23
- data/lib/tty/prompt/statement.rb +3 -3
- data/lib/tty/prompt/suggestion.rb +7 -6
- data/lib/tty/prompt/symbols.rb +58 -58
- data/lib/tty/prompt/test.rb +36 -0
- data/lib/tty/prompt/utils.rb +1 -3
- data/lib/tty/prompt/version.rb +1 -1
- metadata +27 -196
- data/Rakefile +0 -8
- data/examples/ask.rb +0 -7
- data/examples/ask_blank.rb +0 -9
- data/examples/ask_valid.rb +0 -12
- data/examples/collect.rb +0 -21
- data/examples/echo.rb +0 -11
- data/examples/enum_select.rb +0 -7
- data/examples/enum_select_disabled.rb +0 -16
- data/examples/enum_select_paged.rb +0 -9
- data/examples/enum_select_wrapped.rb +0 -15
- data/examples/expand.rb +0 -29
- data/examples/expand_auto.rb +0 -29
- data/examples/in.rb +0 -9
- data/examples/inputs.rb +0 -10
- data/examples/key_events.rb +0 -15
- data/examples/keypress.rb +0 -9
- data/examples/mask.rb +0 -13
- data/examples/multi_select.rb +0 -8
- data/examples/multi_select_disabled.rb +0 -17
- data/examples/multi_select_disabled_paged.rb +0 -22
- data/examples/multi_select_paged.rb +0 -9
- data/examples/multi_select_wrapped.rb +0 -15
- data/examples/multiline.rb +0 -9
- data/examples/pause.rb +0 -9
- data/examples/select.rb +0 -24
- data/examples/select_disabled.rb +0 -18
- data/examples/select_disabled_paged.rb +0 -22
- data/examples/select_enum.rb +0 -8
- data/examples/select_filtered.rb +0 -11
- data/examples/select_paginated.rb +0 -11
- data/examples/select_wrapped.rb +0 -15
- data/examples/slider.rb +0 -6
- data/examples/validation.rb +0 -9
- data/examples/yes_no.rb +0 -7
- data/lib/tty/prompt/messages.rb +0 -49
- data/lib/tty/test_prompt.rb +0 -20
- data/spec/spec_helper.rb +0 -61
- data/spec/unit/ask_spec.rb +0 -173
- data/spec/unit/block_paginator_spec.rb +0 -84
- data/spec/unit/choice/eql_spec.rb +0 -22
- data/spec/unit/choice/from_spec.rb +0 -112
- data/spec/unit/choices/add_spec.rb +0 -12
- data/spec/unit/choices/each_spec.rb +0 -13
- data/spec/unit/choices/find_by_spec.rb +0 -10
- data/spec/unit/choices/new_spec.rb +0 -10
- data/spec/unit/choices/pluck_spec.rb +0 -9
- data/spec/unit/collect_spec.rb +0 -96
- data/spec/unit/converters/convert_bool_spec.rb +0 -58
- data/spec/unit/converters/convert_char_spec.rb +0 -11
- data/spec/unit/converters/convert_custom_spec.rb +0 -14
- data/spec/unit/converters/convert_date_spec.rb +0 -34
- data/spec/unit/converters/convert_file_spec.rb +0 -18
- data/spec/unit/converters/convert_number_spec.rb +0 -39
- data/spec/unit/converters/convert_path_spec.rb +0 -15
- data/spec/unit/converters/convert_range_spec.rb +0 -22
- data/spec/unit/converters/convert_regex_spec.rb +0 -12
- data/spec/unit/converters/convert_string_spec.rb +0 -21
- data/spec/unit/converters/on_error_spec.rb +0 -9
- data/spec/unit/distance/distance_spec.rb +0 -73
- data/spec/unit/enum_select_spec.rb +0 -518
- data/spec/unit/error_spec.rb +0 -20
- data/spec/unit/evaluator_spec.rb +0 -67
- data/spec/unit/expand_spec.rb +0 -290
- data/spec/unit/keypress_spec.rb +0 -66
- data/spec/unit/mask_spec.rb +0 -140
- data/spec/unit/multi_select_spec.rb +0 -741
- data/spec/unit/multiline_spec.rb +0 -77
- data/spec/unit/new_spec.rb +0 -20
- data/spec/unit/ok_spec.rb +0 -10
- data/spec/unit/paginator_spec.rb +0 -92
- data/spec/unit/question/checks_spec.rb +0 -97
- data/spec/unit/question/default_spec.rb +0 -31
- data/spec/unit/question/echo_spec.rb +0 -38
- data/spec/unit/question/in_spec.rb +0 -115
- data/spec/unit/question/initialize_spec.rb +0 -12
- data/spec/unit/question/modifier/apply_to_spec.rb +0 -24
- data/spec/unit/question/modifier/letter_case_spec.rb +0 -41
- data/spec/unit/question/modifier/whitespace_spec.rb +0 -51
- data/spec/unit/question/modify_spec.rb +0 -41
- data/spec/unit/question/required_spec.rb +0 -92
- data/spec/unit/question/validate_spec.rb +0 -115
- data/spec/unit/question/validation/call_spec.rb +0 -31
- data/spec/unit/question/validation/coerce_spec.rb +0 -30
- data/spec/unit/result_spec.rb +0 -40
- data/spec/unit/say_spec.rb +0 -67
- data/spec/unit/select_spec.rb +0 -942
- data/spec/unit/slider_spec.rb +0 -142
- data/spec/unit/statement/initialize_spec.rb +0 -15
- data/spec/unit/subscribe_spec.rb +0 -22
- data/spec/unit/suggest_spec.rb +0 -28
- data/spec/unit/timer_spec.rb +0 -29
- data/spec/unit/warn_spec.rb +0 -21
- data/spec/unit/yes_no_spec.rb +0 -251
- data/tasks/console.rake +0 -11
- data/tasks/coverage.rake +0 -11
- data/tasks/spec.rake +0 -29
- data/tty-prompt.gemspec +0 -31
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 69ced9f6a4234a7234fc2dbce1bc17a982afd2922d7a5c30e0f57030c0970e01
|
4
|
+
data.tar.gz: 26835914ed361e5617660f8bbd9106c101d2963a6e7ae335c4c57ed910658773
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 767a3e943e5740eddbcf14fe9d25fd1d14054402c45d7020762b2cc78842720699223ec27fd229ea70cfb47ab6879b5fd144a76073e44092ed4b8eca1a56e357
|
7
|
+
data.tar.gz: 65b4c4d5ec2d06b900ef4bbd2012eb12c1c1952fe2b7c8ba1865714393da5c34f232a13a35bbefeee870b57d2cb741c77586725bd00a3a1e6a7a61521dfb8c13
|
data/CHANGELOG.md
CHANGED
@@ -1,5 +1,81 @@
|
|
1
1
|
# Change log
|
2
2
|
|
3
|
+
## [v0.23.1] - 2021-04-17
|
4
|
+
|
5
|
+
### Changed
|
6
|
+
* Change validate to allow access to invalid input inside the message
|
7
|
+
|
8
|
+
### Fixed
|
9
|
+
* Fix Choice#from to differentiate between no value being set and nil value
|
10
|
+
|
11
|
+
## [v0.23.0] - 2020-12-14
|
12
|
+
|
13
|
+
### Added
|
14
|
+
* Add the ability to provide an arbitrary array of values to Prompt::Slider by Katelyn Schiesser (@slowbro)
|
15
|
+
|
16
|
+
### Changed
|
17
|
+
* Change to allow default option to be choice name as well as index in select, multi_select and enum_select prompts
|
18
|
+
|
19
|
+
### Fixed
|
20
|
+
* Fix left and right key navigation while filtering choices in the #select and #multi_select prompts
|
21
|
+
|
22
|
+
## [v0.22.0] - 2020-07-20
|
23
|
+
|
24
|
+
### Added
|
25
|
+
* Add #slider format customization with a proc by Sven Pchnit(@2called-chaos)
|
26
|
+
* Add convert message customization
|
27
|
+
* Add conversion of input into Array, Hash or URI object
|
28
|
+
* Add callable objects as possible values in :active_color and :help_color
|
29
|
+
* Add shortcuts to select of all/reverse choices in #multi_select prompt
|
30
|
+
* Add :help option to #slider prompt
|
31
|
+
* Add :quiet option to remove final prompt output by Katelyn Schiesser (@slowbro)
|
32
|
+
* Add :show_help option to control help display in #select, #multi_select, #enum_select
|
33
|
+
and #slider prompts
|
34
|
+
|
35
|
+
### Changed
|
36
|
+
* Changed question :validation option to :validate by Sven Pachnit(@2called-chaos)
|
37
|
+
* Change ConverterRegistry to store only proc values and simplify interface
|
38
|
+
* Change Converters to stop raising errors and print console error messages instead
|
39
|
+
* Change :range conversion to handle float numbers
|
40
|
+
* Change yes?/no? prompt to infer default value from words and raise when
|
41
|
+
no boolean can be deduced
|
42
|
+
* Change Prompt#new to use keyword arguments
|
43
|
+
* Change #select/#multi_select prompts default help text
|
44
|
+
* Change #multi_select to preserve original ordering in returned answers
|
45
|
+
* Change to remove necromancer dependency
|
46
|
+
* Change TTY::TestPrompt to TTY::Prompt::Test
|
47
|
+
* Change #select,#multi_select & #enum_select to allow mix of options and block parameters configuration
|
48
|
+
* Change to allow filtering through symbol choice names
|
49
|
+
* Change all errors to inherit from common Error class
|
50
|
+
|
51
|
+
### Fixed
|
52
|
+
* Fix multiline prompt to return default value when no input provided
|
53
|
+
* Fix color option overriding in say, ok, error and warn prompts
|
54
|
+
* Fix Prompt#inspect format to display all public attributes
|
55
|
+
|
56
|
+
## [v0.21.0] - 2020-03-08
|
57
|
+
|
58
|
+
### Added
|
59
|
+
* Add :min option to #multi_select prompt by Katelyn Schiesser(@slowbro)
|
60
|
+
|
61
|
+
### Changed
|
62
|
+
* Change gemspec to remove test artifacts
|
63
|
+
|
64
|
+
### Fixed
|
65
|
+
* Fix :help_color option for multi_select prompt by @robbystk
|
66
|
+
|
67
|
+
## [v0.20.0] - 2019-11-24
|
68
|
+
|
69
|
+
### Changed
|
70
|
+
* Change to update tty-reader dependency
|
71
|
+
* Change gemspec to include metadata
|
72
|
+
|
73
|
+
### Fixed
|
74
|
+
* Fix Choice#from to differentiate between nil and false by Katelyn Schiesser(@slowbro)
|
75
|
+
* Fix yes? and no? prompts to stop raising on invalid/blank input by Katelyn Schiesser(@slowbro)
|
76
|
+
* Fix Ruby 2.7 keyword arguments warnings
|
77
|
+
* Fix question validation to work with nil input
|
78
|
+
|
3
79
|
## [v0.19.0] - 2019-05-27
|
4
80
|
|
5
81
|
### Added
|
@@ -326,6 +402,11 @@
|
|
326
402
|
|
327
403
|
* Initial implementation and release
|
328
404
|
|
405
|
+
[v0.23.1]: https://github.com/piotrmurach/tty-prompt/compare/v0.23.0...v0.23.1
|
406
|
+
[v0.23.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.22.0...v0.23.0
|
407
|
+
[v0.22.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.21.0...v0.22.0
|
408
|
+
[v0.21.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.20.0...v0.21.0
|
409
|
+
[v0.20.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.19.0...v0.20.0
|
329
410
|
[v0.19.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.18.1...v0.19.0
|
330
411
|
[v0.18.1]: https://github.com/piotrmurach/tty-prompt/compare/v0.18.0...v0.18.1
|
331
412
|
[v0.18.0]: https://github.com/piotrmurach/tty-prompt/compare/v0.17.2...v0.18.0
|
data/LICENSE.txt
CHANGED
data/README.md
CHANGED
@@ -1,11 +1,11 @@
|
|
1
1
|
<div align="center">
|
2
|
-
<a href="https://
|
2
|
+
<a href="https://ttytoolkit.org"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="TTY Toolkit logo" /></a>
|
3
3
|
</div>
|
4
4
|
|
5
5
|
# TTY::Prompt [][gitter]
|
6
6
|
|
7
7
|
[][gem]
|
8
|
-
[][gh_actions_ci]
|
9
9
|
[][appveyor]
|
10
10
|
[][codeclimate]
|
11
11
|
[][coverage]
|
@@ -13,6 +13,7 @@
|
|
13
13
|
|
14
14
|
[gitter]: https://gitter.im/piotrmurach/tty
|
15
15
|
[gem]: http://badge.fury.io/rb/tty-prompt
|
16
|
+
[gh_actions_ci]: https://github.com/piotrmurach/tty-prompt/actions?query=workflow%3ACI
|
16
17
|
[travis]: http://travis-ci.org/piotrmurach/tty-prompt
|
17
18
|
[appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-prompt
|
18
19
|
[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-prompt
|
@@ -47,7 +48,7 @@ For Windows, consider installing [ConEmu](https://conemu.github.io/), [cmder](ht
|
|
47
48
|
Add this line to your application's Gemfile:
|
48
49
|
|
49
50
|
```ruby
|
50
|
-
gem
|
51
|
+
gem "tty-prompt"
|
51
52
|
```
|
52
53
|
|
53
54
|
And then execute:
|
@@ -63,15 +64,15 @@ Or install it yourself as:
|
|
63
64
|
* [1. Usage](#1-usage)
|
64
65
|
* [2. Interface](#2-interface)
|
65
66
|
* [2.1 ask](#21-ask)
|
66
|
-
* [2.1.1 convert](#211-convert)
|
67
|
-
* [2.1.2 default](#212-default)
|
68
|
-
* [2.1.3 value](#213-value)
|
69
|
-
* [2.1.4 echo](#214-echo)
|
67
|
+
* [2.1.1 :convert](#211-convert)
|
68
|
+
* [2.1.2 :default](#212-default)
|
69
|
+
* [2.1.3 :value](#213-value)
|
70
|
+
* [2.1.4 :echo](#214-echo)
|
70
71
|
* [2.1.5 error messages](#215-error-messages)
|
71
|
-
* [2.1.6 in](#216-in)
|
72
|
-
* [2.1.7 modify](#217-modify)
|
73
|
-
* [2.1.8 required](#218-required)
|
74
|
-
* [2.1.9 validate](#219-validate)
|
72
|
+
* [2.1.6 :in](#216-in)
|
73
|
+
* [2.1.7 :modify](#217-modify)
|
74
|
+
* [2.1.8 :required](#218-required)
|
75
|
+
* [2.1.9 :validate](#219-validate)
|
75
76
|
* [2.2 keypress](#22-keypress)
|
76
77
|
* [2.2.1 :timeout](#221-timeout)
|
77
78
|
* [2.3 multiline](#23-multiline)
|
@@ -81,19 +82,28 @@ Or install it yourself as:
|
|
81
82
|
* [2.6.1 choices](#261-choices)
|
82
83
|
* [2.6.1.1 :disabled](#2611-disabled)
|
83
84
|
* [2.6.2 select](#262-select)
|
84
|
-
* [2.6.2.1 :
|
85
|
-
* [2.6.2.2 :
|
86
|
-
* [2.6.2.3 :
|
85
|
+
* [2.6.2.1 :cycle](#2621-cycle)
|
86
|
+
* [2.6.2.2 :enum](#2622-enum)
|
87
|
+
* [2.6.2.3 :help](#2623-help)
|
88
|
+
* [2.6.2.4 :marker](#2624-marker)
|
89
|
+
* [2.6.2.5 :per_page](#2625-per_page)
|
90
|
+
* [2.6.2.6 :disabled](#2626-disabled)
|
91
|
+
* [2.6.2.7 :filter](#2627-filter)
|
87
92
|
* [2.6.3 multi_select](#263-multi_select)
|
88
|
-
* [2.6.3.1 :
|
89
|
-
* [2.6.3.2 :
|
90
|
-
* [2.6.3.3 :
|
91
|
-
* [2.6.3.4 :
|
93
|
+
* [2.6.3.1 :cycle](#2631-cycle)
|
94
|
+
* [2.6.3.2 :enum](#2632-enum)
|
95
|
+
* [2.6.3.3 :help](#2633-help)
|
96
|
+
* [2.6.3.4 :per_page](#2634-per_page)
|
97
|
+
* [2.6.3.5 :disabled](#2635-disabled)
|
98
|
+
* [2.6.3.6 :echo](#2636-echo)
|
99
|
+
* [2.6.3.7 :filter](#2637-filter)
|
100
|
+
* [2.6.3.8 :min](#2638-min)
|
101
|
+
* [2.6.3.9 :max](#2639-max)
|
92
102
|
* [2.6.4 enum_select](#264-enum_select)
|
93
103
|
* [2.6.4.1 :per_page](#2641-per_page)
|
94
104
|
* [2.6.4.1 :disabled](#2641-disabled)
|
95
105
|
* [2.7 expand](#27-expand)
|
96
|
-
* [2.7.1 auto_hint](#271-auto_hint)
|
106
|
+
* [2.7.1 :auto_hint](#271-auto_hint)
|
97
107
|
* [2.8 collect](#28-collect)
|
98
108
|
* [2.9 suggest](#29-suggest)
|
99
109
|
* [2.10 slider](#210-slider)
|
@@ -105,31 +115,34 @@ Or install it yourself as:
|
|
105
115
|
* [3. settings](#3-settings)
|
106
116
|
* [3.1 :symbols](#31-symbols)
|
107
117
|
* [3.2 :active_color](#32-active_color)
|
108
|
-
* [3.3 :enable_color](#33-
|
118
|
+
* [3.3 :enable_color](#33-enable_color)
|
109
119
|
* [3.4 :help_color](#34-help_color)
|
110
120
|
* [3.5 :interrupt](#35-interrupt)
|
111
121
|
* [3.6 :prefix](#36-prefix)
|
112
|
-
* [3.7 :
|
122
|
+
* [3.7 :quiet](#37-quiet)
|
123
|
+
* [3.8 :track_history](#38-track_history)
|
113
124
|
|
114
125
|
## 1. Usage
|
115
126
|
|
116
127
|
In order to start asking questions on the command line, create prompt:
|
117
128
|
|
118
129
|
```ruby
|
130
|
+
require "tty-prompt"
|
131
|
+
|
119
132
|
prompt = TTY::Prompt.new
|
120
133
|
```
|
121
134
|
|
122
135
|
And then call `ask` with the question for simple input:
|
123
136
|
|
124
137
|
```ruby
|
125
|
-
prompt.ask(
|
138
|
+
prompt.ask("What is your name?", default: ENV["USER"])
|
126
139
|
# => What is your name? (piotr)
|
127
140
|
```
|
128
141
|
|
129
142
|
To confirm input use `yes?`:
|
130
143
|
|
131
144
|
```ruby
|
132
|
-
prompt.yes?(
|
145
|
+
prompt.yes?("Do you like Ruby?")
|
133
146
|
# => Do you like Ruby? (Y/n)
|
134
147
|
```
|
135
148
|
|
@@ -184,13 +197,13 @@ However, if you have a lot of options to choose from you may want to use `expand
|
|
184
197
|
|
185
198
|
```ruby
|
186
199
|
choices = [
|
187
|
-
{ key:
|
188
|
-
{ key:
|
189
|
-
{ key:
|
190
|
-
{ key:
|
191
|
-
{ key:
|
200
|
+
{ key: "y", name: "overwrite this file", value: :yes },
|
201
|
+
{ key: "n", name: "do not overwrite this file", value: :no },
|
202
|
+
{ key: "a", name: "overwrite this file and all later files", value: :all },
|
203
|
+
{ key: "d", name: "show diff", value: :diff },
|
204
|
+
{ key: "q", name: "quit; do not overwrite this file ", value: :quit }
|
192
205
|
]
|
193
|
-
prompt.expand(
|
206
|
+
prompt.expand("Overwrite Gemfile?", choices)
|
194
207
|
# =>
|
195
208
|
# Overwrite Gemfile? (enter "h" for help) [y,n,a,d,q,h]
|
196
209
|
```
|
@@ -199,14 +212,14 @@ If you wish to collect more than one answer use `collect`:
|
|
199
212
|
|
200
213
|
```ruby
|
201
214
|
result = prompt.collect do
|
202
|
-
key(:name).ask(
|
215
|
+
key(:name).ask("Name?")
|
203
216
|
|
204
|
-
key(:age).ask(
|
217
|
+
key(:age).ask("Age?", convert: :int)
|
205
218
|
|
206
219
|
key(:address) do
|
207
|
-
key(:street).ask(
|
208
|
-
key(:city).ask(
|
209
|
-
key(:zip).ask(
|
220
|
+
key(:street).ask("Street?", required: true)
|
221
|
+
key(:city).ask("City?")
|
222
|
+
key(:zip).ask("Zip?", validate: /\A\d{3}\Z/)
|
210
223
|
end
|
211
224
|
end
|
212
225
|
# =>
|
@@ -233,25 +246,41 @@ prompt.ask("What is your name?") do |q|
|
|
233
246
|
end
|
234
247
|
```
|
235
248
|
|
236
|
-
#### 2.1.1 convert
|
249
|
+
#### 2.1.1 `:convert`
|
237
250
|
|
238
251
|
The `convert` property is used to convert input to a required type.
|
239
252
|
|
240
|
-
By default no conversion is performed.
|
253
|
+
By default no conversion of input is performed. To change this use one of the following conversions:
|
241
254
|
|
242
|
-
|
243
|
-
|
244
|
-
|
245
|
-
|
246
|
-
|
247
|
-
|
248
|
-
|
249
|
-
|
250
|
-
|
251
|
-
|
252
|
-
|
253
|
-
|
254
|
-
|
255
|
+
* `:boolean`|`:bool` - e.g. 'yes/1/y/t/' becomes `true`, 'no/0/n/f' becomes `false`
|
256
|
+
* `:date` - parses dates formats "28/03/2020", "March 28th 2020"
|
257
|
+
* `:time` - parses time formats "11:20:03"
|
258
|
+
* `:float` - e.g. `-1` becomes `-1.0`
|
259
|
+
* `:int`|`:integer` - e.g. `+1` becomes `1`
|
260
|
+
* `:sym`|`:symbol` - e.g. "foo" becomes `:foo`
|
261
|
+
* `:filepath` - converts to file path
|
262
|
+
* `:path`|`:pathname` - converts to `Pathname` object
|
263
|
+
* `:range` - e.g. '1-10' becomes `1..10` range object
|
264
|
+
* `:regexp` - e.g. "foo|bar" becomes `/foo|bar/`
|
265
|
+
* `:uri` - converts to `URI` object
|
266
|
+
* `:list`|`:array` - e.g. 'a,b,c' becomes `["a", "b", "c"]`
|
267
|
+
* `:map`|`:hash` - e.g. 'a:1 b:2 c:3' becomes `{a: "1", b: "2", c: "3"}`
|
268
|
+
|
269
|
+
In addition you can specify a plural or append `list` or `array` to any base type:
|
270
|
+
|
271
|
+
* `:ints` or `:int_list` - will convert to a list of integers
|
272
|
+
* `:floats` or `:float_list` - will convert to a list of floats
|
273
|
+
* `:bools` or `:bool_list` - will convert to a list of booleans, e.g. `t,f,t` becomes `[true, false, true]`
|
274
|
+
|
275
|
+
Similarly, you can append `map` or `hash` to any base type:
|
276
|
+
|
277
|
+
* `: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}`
|
278
|
+
* `: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}`
|
279
|
+
|
280
|
+
By default, `map` converts keys to symbols, if you wish to use strings instead specify key type like so:
|
281
|
+
|
282
|
+
* `:str_int_map` - will convert to a hash of string keys and integer values
|
283
|
+
* `:string_integer_hash` - will convert to a hash of string keys and integer values
|
255
284
|
|
256
285
|
For example, if you are interested in range type as answer do the following:
|
257
286
|
|
@@ -261,27 +290,54 @@ prompt.ask("Provide range of numbers?", convert: :range)
|
|
261
290
|
# => 1..10
|
262
291
|
```
|
263
292
|
|
293
|
+
If, on the other hand, you wish to convert input to a hash of integer values do:
|
294
|
+
|
295
|
+
```ruby
|
296
|
+
prompt.ask("Provide keys and values:", convert: :int_map)
|
297
|
+
# Provide keys and values: a=1 b=2 c=3
|
298
|
+
# => {a: 1, b: 2, c: 3}
|
299
|
+
```
|
300
|
+
|
301
|
+
If a user provides a wrong type for conversion an error message will be printed in the console:
|
302
|
+
|
303
|
+
```ruby
|
304
|
+
prompt.ask("Provide digit:", convert: :float)
|
305
|
+
# Provide digit: x
|
306
|
+
# >> Cannot convert `x` into 'float' type
|
307
|
+
```
|
308
|
+
|
309
|
+
You can further customize error message:
|
310
|
+
|
311
|
+
```ruby
|
312
|
+
prompt.ask("Provide digit:", convert: :float) do |q|
|
313
|
+
q.convert(:float, "Wrong value of %{value} for %{type} conversion")
|
314
|
+
# or
|
315
|
+
q.convert :float
|
316
|
+
q.messages[:convert?] = "Wrong value of %{value} for %{type} conversion"
|
317
|
+
end
|
318
|
+
```
|
319
|
+
|
264
320
|
You can also provide a custom conversion like so:
|
265
321
|
|
266
322
|
```ruby
|
267
|
-
prompt.ask(
|
323
|
+
prompt.ask("Ingredients? (comma sep list)") do |q|
|
268
324
|
q.convert -> (input) { input.split(/,\s*/) }
|
269
325
|
end
|
270
326
|
# Ingredients? (comma sep list) milk, eggs, flour
|
271
|
-
# => [
|
327
|
+
# => ["milk", "eggs", "flour"]
|
272
328
|
```
|
273
329
|
|
274
|
-
#### 2.1.2 default
|
330
|
+
#### 2.1.2 `:default`
|
275
331
|
|
276
332
|
The `:default` option is used if the user presses return key:
|
277
333
|
|
278
334
|
```ruby
|
279
|
-
prompt.ask(
|
335
|
+
prompt.ask("What is your name?", default: "Anonymous")
|
280
336
|
# =>
|
281
337
|
# What is your name? (Anonymous)
|
282
338
|
```
|
283
339
|
|
284
|
-
#### 2.1.3 value
|
340
|
+
#### 2.1.3 `:value`
|
285
341
|
|
286
342
|
To pre-populate the input line for editing use `:value` option:
|
287
343
|
|
@@ -291,58 +347,58 @@ prompt.ask("What is your name?", value: "Piotr")
|
|
291
347
|
# What is your name? Piotr
|
292
348
|
```
|
293
349
|
|
294
|
-
#### 2.1.4 echo
|
350
|
+
#### 2.1.4 `:echo`
|
295
351
|
|
296
352
|
To control whether the input is shown back in terminal or not use `:echo` option like so:
|
297
353
|
|
298
354
|
```ruby
|
299
|
-
prompt.ask(
|
355
|
+
prompt.ask("password:", echo: false)
|
300
356
|
```
|
301
357
|
|
302
358
|
#### 2.1.5 error messages
|
303
359
|
|
304
|
-
By default `tty-prompt` comes with predefined error messages for `required`, `in`, `validate` options.
|
360
|
+
By default `tty-prompt` comes with predefined error messages for `convert`, `required`, `in`, `validate` options.
|
305
361
|
|
306
362
|
You can change these and configure to your liking either by passing message as second argument with the option:
|
307
363
|
|
308
364
|
```ruby
|
309
|
-
prompt.ask(
|
310
|
-
q.validate(/\A\w+@\w+\.\w+\Z/,
|
365
|
+
prompt.ask("What is your email?") do |q|
|
366
|
+
q.validate(/\A\w+@\w+\.\w+\Z/, "Invalid email address")
|
311
367
|
end
|
312
368
|
```
|
313
369
|
|
314
|
-
Or change the `messages` key entry out of `:
|
370
|
+
Or change the `messages` key entry out of `:convert?`, `:range?`, `:required?` and `:valid?`:
|
315
371
|
|
316
372
|
```ruby
|
317
|
-
prompt.ask(
|
373
|
+
prompt.ask("What is your email?") do |q|
|
318
374
|
q.validate(/\A\w+@\w+\.\w+\Z/)
|
319
|
-
q.messages[:valid?] =
|
375
|
+
q.messages[:valid?] = "Invalid email address"
|
320
376
|
end
|
321
377
|
```
|
322
378
|
|
323
379
|
To change default range validation error message do:
|
324
380
|
|
325
381
|
```ruby
|
326
|
-
prompt.ask(
|
327
|
-
q.in
|
328
|
-
q.messages[:range?] =
|
382
|
+
prompt.ask("How spicy on scale (1-5)? ") do |q|
|
383
|
+
q.in "1-5"
|
384
|
+
q.messages[:range?] = "%{value} out of expected range %{in}"
|
329
385
|
end
|
330
386
|
```
|
331
387
|
|
332
|
-
#### 2.1.6 in
|
388
|
+
#### 2.1.6 `:in`
|
333
389
|
|
334
390
|
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:
|
335
391
|
|
336
392
|
```ruby
|
337
|
-
ask("Provide number in range: 0-9?") { |q| q.in(
|
393
|
+
prompt.ask("Provide number in range: 0-9?") { |q| q.in("0-9") }
|
338
394
|
```
|
339
395
|
|
340
|
-
#### 2.1.7 modify
|
396
|
+
#### 2.1.7 `:modify`
|
341
397
|
|
342
398
|
Set the `:modify` option if you want to handle whitespace or letter capitalization.
|
343
399
|
|
344
400
|
```ruby
|
345
|
-
prompt.ask(
|
401
|
+
prompt.ask("Enter text:") do |q|
|
346
402
|
q.modify :strip, :collapse
|
347
403
|
end
|
348
404
|
```
|
@@ -355,14 +411,16 @@ Available letter casing settings are:
|
|
355
411
|
```
|
356
412
|
|
357
413
|
Available whitespace settings are:
|
414
|
+
|
358
415
|
```ruby
|
359
416
|
:trim # remove whitespace from both ends of the input
|
417
|
+
:strip # same as :trim
|
360
418
|
:chomp # remove whitespace at the end of input
|
361
419
|
:collapse # reduce all whitespace to single character
|
362
420
|
:remove # remove all whitespace
|
363
421
|
```
|
364
422
|
|
365
|
-
#### 2.1.8 required
|
423
|
+
#### 2.1.8 `:required`
|
366
424
|
|
367
425
|
To ensure that input is provided use `:required` option:
|
368
426
|
|
@@ -372,20 +430,47 @@ prompt.ask("What's your phone number?", required: true)
|
|
372
430
|
# >> Value must be provided
|
373
431
|
```
|
374
432
|
|
375
|
-
#### 2.1.9 validate
|
433
|
+
#### 2.1.9 `:validate`
|
434
|
+
|
435
|
+
In order to validate that input matches a given pattern you can pass the `validate` option/method.
|
436
|
+
|
437
|
+
Validate accepts `Regex`, `Proc` or `Symbol`.
|
438
|
+
|
439
|
+
```ruby
|
440
|
+
prompt.ask("What is your username?") do |q|
|
441
|
+
q.validate(/\A[^.]+\.[^.]+\Z/)
|
442
|
+
end
|
443
|
+
```
|
444
|
+
|
445
|
+
The above can also be expressed as a `Proc`:
|
446
|
+
|
447
|
+
```ruby
|
448
|
+
prompt.ask("What is your username?") do |q|
|
449
|
+
q.validate ->(input) { input =~ /\A[^.]+\.[^.]+\Z/ }
|
450
|
+
end
|
451
|
+
```
|
452
|
+
|
453
|
+
There is a built-in validation for `:email` and you can use it directly like so:
|
454
|
+
|
455
|
+
```ruby
|
456
|
+
prompt.ask("What is your email?") { |q| q.validate :email }
|
457
|
+
```
|
376
458
|
|
377
|
-
|
459
|
+
The default validation message is `"Your answer is invalid (must match %{valid})"` and you can customise it by passing in a second argument:
|
378
460
|
|
379
461
|
```ruby
|
380
|
-
prompt.ask(
|
381
|
-
q.validate
|
462
|
+
prompt.ask("What is your username?") do |q|
|
463
|
+
q.validate(/\A[^.]+\.[^.]+\Z/, "Invalid username: %{value}, must match %{valid}")
|
382
464
|
end
|
383
465
|
```
|
384
466
|
|
385
|
-
The
|
467
|
+
The default message can also be set using `messages` and the `:valid?` key:
|
386
468
|
|
387
|
-
```
|
388
|
-
prompt.ask(
|
469
|
+
```ruby
|
470
|
+
prompt.ask("What is your username?") do |q|
|
471
|
+
q.validate(/\A[^.]+\.[^.]+\Z/)
|
472
|
+
q.messages[:valid?] = "Invalid username: %{value}, must match %{valid}")
|
473
|
+
end
|
389
474
|
```
|
390
475
|
|
391
476
|
### 2.2. keypress
|
@@ -428,21 +513,22 @@ prompt.multiline("Description?")
|
|
428
513
|
# I know not all that may be coming,
|
429
514
|
# but be it what it will,
|
430
515
|
# I'll go to it laughing.
|
431
|
-
# =>
|
516
|
+
# =>
|
517
|
+
# ["I know not all that may be coming,\n", "but be it what it will,\n", "I'll go to it laughing.\n"]
|
432
518
|
```
|
433
519
|
|
434
520
|
The `multiline` uses similar options to those supported by `ask` prompt. For example, to provide default description:
|
435
521
|
|
436
522
|
```ruby
|
437
|
-
prompt.multiline("Description?", default:
|
523
|
+
prompt.multiline("Description?", default: "A super sweet prompt.")
|
438
524
|
```
|
439
525
|
|
440
526
|
Or using DSL:
|
441
527
|
|
442
528
|
```ruby
|
443
529
|
prompt.multiline("Description?") do |q|
|
444
|
-
q.default
|
445
|
-
q.help
|
530
|
+
q.default "A super sweet prompt."
|
531
|
+
q.help "Press thy ctrl+d to end"
|
446
532
|
end
|
447
533
|
```
|
448
534
|
|
@@ -451,28 +537,28 @@ end
|
|
451
537
|
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.
|
452
538
|
|
453
539
|
```ruby
|
454
|
-
prompt.mask(
|
540
|
+
prompt.mask("What is your secret?")
|
455
541
|
# => What is your secret? ••••
|
456
542
|
```
|
457
543
|
|
458
|
-
The masking character can be changed by passing
|
544
|
+
The masking character can be changed by passing the `:mask` key:
|
459
545
|
|
460
546
|
```ruby
|
461
|
-
heart = prompt.decorate(prompt.symbols[:heart] +
|
462
|
-
prompt.mask(
|
547
|
+
heart = prompt.decorate(prompt.symbols[:heart] + " ", :magenta)
|
548
|
+
prompt.mask("What is your secret?", mask: heart)
|
463
549
|
# => What is your secret? ❤ ❤ ❤ ❤ ❤
|
464
550
|
```
|
465
551
|
|
466
552
|
If you don't wish to show any output use `:echo` option like so:
|
467
553
|
|
468
554
|
```ruby
|
469
|
-
prompt.mask(
|
555
|
+
prompt.mask("What is your secret?", echo: false)
|
470
556
|
```
|
471
557
|
|
472
558
|
You can also provide validation for your mask to enforce for instance strong passwords:
|
473
559
|
|
474
560
|
```ruby
|
475
|
-
prompt.mask(
|
561
|
+
prompt.mask("What is your secret?", mask: heart) do |q|
|
476
562
|
q.validate(/[a-z\ ]{5,15}/)
|
477
563
|
end
|
478
564
|
```
|
@@ -482,7 +568,7 @@ end
|
|
482
568
|
In order to display a query asking for boolean input from user use `yes?` like so:
|
483
569
|
|
484
570
|
```ruby
|
485
|
-
prompt.yes?(
|
571
|
+
prompt.yes?("Do you like Ruby?")
|
486
572
|
# =>
|
487
573
|
# Do you like Ruby? (Y/n)
|
488
574
|
```
|
@@ -493,7 +579,7 @@ It's enough to provide the `suffix` option for the prompt to accept matching ans
|
|
493
579
|
|
494
580
|
```ruby
|
495
581
|
prompt.yes?("Are you a human?") do |q|
|
496
|
-
q.suffix
|
582
|
+
q.suffix "Yup/nope"
|
497
583
|
end
|
498
584
|
# =>
|
499
585
|
# Are you a human? (Yup/nope)
|
@@ -504,8 +590,8 @@ Alternatively, instead of `suffix` option provide the `positive` and `negative`
|
|
504
590
|
```ruby
|
505
591
|
prompt.yes?("Are you a human?") do |q|
|
506
592
|
q.default false
|
507
|
-
q.positive
|
508
|
-
q.negative
|
593
|
+
q.positive "Yup"
|
594
|
+
q.negative "Nope"
|
509
595
|
end
|
510
596
|
# =>
|
511
597
|
# Are you a human? (yup/Nope)
|
@@ -514,10 +600,10 @@ end
|
|
514
600
|
Finally, providing all available options you can ask fully customized question:
|
515
601
|
|
516
602
|
```ruby
|
517
|
-
prompt.yes?(
|
518
|
-
q.suffix
|
519
|
-
q.positive
|
520
|
-
q.negative
|
603
|
+
prompt.yes?("Are you a human?") do |q|
|
604
|
+
q.suffix "Agree/Disagree"
|
605
|
+
q.positive "Agree"
|
606
|
+
q.negative "Disagree"
|
521
607
|
q.convert -> (input) { !input.match(/^agree$/i).nil? }
|
522
608
|
end
|
523
609
|
# =>
|
@@ -527,7 +613,7 @@ end
|
|
527
613
|
There is also the opposite for asking confirmation of negative question:
|
528
614
|
|
529
615
|
```ruby
|
530
|
-
prompt.no?(
|
616
|
+
prompt.no?("Do you hate Ruby?")
|
531
617
|
# =>
|
532
618
|
# Do you hate Ruby? (y/N)
|
533
619
|
```
|
@@ -548,15 +634,21 @@ By default the choice name is also the value the prompt will return when selecte
|
|
548
634
|
|
549
635
|
```ruby
|
550
636
|
choices = {small: 1, medium: 2, large: 3}
|
637
|
+
prompt.select("What size?", choices)
|
638
|
+
# =>
|
639
|
+
# What size? (Press ↑/↓ arrow to move and Enter to select)
|
640
|
+
# ‣ small
|
641
|
+
# medium
|
642
|
+
# large
|
551
643
|
```
|
552
644
|
|
553
645
|
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:
|
554
646
|
|
555
647
|
```ruby
|
556
648
|
choices = [
|
557
|
-
{name:
|
558
|
-
{name:
|
559
|
-
{name:
|
649
|
+
{name: "small", value: 1},
|
650
|
+
{name: "medium", value: 2, disabled: "(out of stock)"},
|
651
|
+
{name: "large", value: 3}
|
560
652
|
]
|
561
653
|
```
|
562
654
|
|
@@ -565,20 +657,25 @@ You can specify `:key` as an additional option which will be used as short name
|
|
565
657
|
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:
|
566
658
|
|
567
659
|
```ruby
|
568
|
-
prompt.select(
|
569
|
-
menu.choice name:
|
570
|
-
menu.choice name:
|
571
|
-
menu.choice name:
|
660
|
+
prompt.select("What size?") do |menu|
|
661
|
+
menu.choice name: "small", value: 1
|
662
|
+
menu.choice name: "medium", value: 2, disabled: "(out of stock)"
|
663
|
+
menu.choice name: "large", value: 3
|
572
664
|
end
|
665
|
+
# =>
|
666
|
+
# What size? (Press ↑/↓ arrow to move and Enter to select)
|
667
|
+
# ‣ small
|
668
|
+
# ✘ medium (out of stock)
|
669
|
+
# large
|
573
670
|
```
|
574
671
|
|
575
672
|
or in a more compact way:
|
576
673
|
|
577
674
|
```ruby
|
578
|
-
prompt.select(
|
579
|
-
menu.choice
|
580
|
-
menu.choice
|
581
|
-
menu.choice
|
675
|
+
prompt.select("What size?") do |menu|
|
676
|
+
menu.choice "small", 1
|
677
|
+
menu.choice "medium", 2, disabled: "(out of stock)"
|
678
|
+
menu.choice "large", 3
|
582
679
|
end
|
583
680
|
```
|
584
681
|
|
@@ -588,9 +685,9 @@ The `:disabled` key indicates to display a choice as currently unavailable to se
|
|
588
685
|
|
589
686
|
```ruby
|
590
687
|
choices = [
|
591
|
-
{name:
|
592
|
-
{name:
|
593
|
-
{name:
|
688
|
+
{name: "small", value: 1},
|
689
|
+
{name: "medium", value: 2, disabled: "(out of stock)"},
|
690
|
+
{name: "large", value: 3}
|
594
691
|
]
|
595
692
|
```
|
596
693
|
|
@@ -611,9 +708,9 @@ You can also provide options through DSL using the `choice` method for single en
|
|
611
708
|
|
612
709
|
```ruby
|
613
710
|
prompt.select("Choose your destiny?") do |menu|
|
614
|
-
menu.choice
|
615
|
-
menu.choice
|
616
|
-
menu.choice
|
711
|
+
menu.choice "Scorpion"
|
712
|
+
menu.choice "Kano"
|
713
|
+
menu.choice "Jax"
|
617
714
|
end
|
618
715
|
# =>
|
619
716
|
# 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
|
|
626
723
|
|
627
724
|
```ruby
|
628
725
|
prompt.select("Choose your destiny?") do |menu|
|
629
|
-
menu.choice
|
630
|
-
menu.choice
|
631
|
-
menu.choice
|
726
|
+
menu.choice "Scorpion", 1
|
727
|
+
menu.choice "Kano", 2
|
728
|
+
menu.choice "Jax", -> { "Nice choice captain!" }
|
632
729
|
end
|
633
730
|
# =>
|
634
731
|
# Choose your destiny? (Use ↑/↓ arrow keys, press Enter to select)
|
@@ -640,19 +737,20 @@ end
|
|
640
737
|
If you wish you can also provide a simple hash to denote choice name and its value like so:
|
641
738
|
|
642
739
|
```ruby
|
643
|
-
choices = {
|
740
|
+
choices = {"Scorpion" => 1, "Kano" => 2, "Jax" => 3}
|
644
741
|
prompt.select("Choose your destiny?", choices)
|
645
742
|
```
|
646
743
|
|
647
|
-
To mark particular answer as selected use `default` with index of the
|
744
|
+
To mark particular answer as selected use `default` with either an index of the choice starting from `1` or a choice's name:
|
648
745
|
|
649
746
|
```ruby
|
650
747
|
prompt.select("Choose your destiny?") do |menu|
|
651
748
|
menu.default 3
|
749
|
+
# or menu.default "Jax"
|
652
750
|
|
653
|
-
menu.choice
|
654
|
-
menu.choice
|
655
|
-
menu.choice
|
751
|
+
menu.choice "Scorpion", 1
|
752
|
+
menu.choice "Kano", 2
|
753
|
+
menu.choice "Jax", 3
|
656
754
|
end
|
657
755
|
# =>
|
658
756
|
# Choose your destiny? (Use ↑/↓ arrow keys, press Enter to select)
|
@@ -661,7 +759,9 @@ end
|
|
661
759
|
# ‣ Jax
|
662
760
|
```
|
663
761
|
|
664
|
-
|
762
|
+
#### 2.6.2.1 `:cycle`
|
763
|
+
|
764
|
+
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`:
|
665
765
|
|
666
766
|
```ruby
|
667
767
|
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)
|
|
672
772
|
# Jax
|
673
773
|
```
|
674
774
|
|
775
|
+
#### 2.6.2.2 `:enum`
|
776
|
+
|
675
777
|
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.
|
676
778
|
|
677
779
|
```ruby
|
678
780
|
prompt.select("Choose your destiny?") do |menu|
|
679
|
-
menu.enum
|
781
|
+
menu.enum "."
|
680
782
|
|
681
|
-
menu.choice
|
682
|
-
menu.choice
|
683
|
-
menu.choice
|
783
|
+
menu.choice "Scorpion", 1
|
784
|
+
menu.choice "Kano", 2
|
785
|
+
menu.choice "Jax", 3
|
684
786
|
end
|
685
787
|
# =>
|
686
788
|
# Choose your destiny? (Use ↑/↓ arrow or number (0-9) keys, press Enter to select)
|
@@ -689,24 +791,40 @@ end
|
|
689
791
|
# ‣ 3. Jax
|
690
792
|
```
|
691
793
|
|
692
|
-
|
794
|
+
#### 2.6.2.3 `:help`
|
795
|
+
|
796
|
+
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`:
|
797
|
+
|
798
|
+
```ruby
|
799
|
+
choices = %w(Scorpion Kano Jax)
|
800
|
+
prompt.select("Choose your destiny?", choices, help: "(Bash keyboard keys)", show_help: :always)
|
801
|
+
# =>
|
802
|
+
# Choose your destiny? (Bash keyboard keys)
|
803
|
+
# > Scorpion
|
804
|
+
# Kano
|
805
|
+
# Jax
|
806
|
+
```
|
807
|
+
|
808
|
+
#### 2.6.2.4 `:marker`
|
809
|
+
|
810
|
+
You can configure active marker like so:
|
693
811
|
|
694
812
|
```ruby
|
695
813
|
choices = %w(Scorpion Kano Jax)
|
696
|
-
prompt.select("Choose your destiny?", choices,
|
814
|
+
prompt.select("Choose your destiny?", choices, symbols: { marker: ">" })
|
697
815
|
# =>
|
698
|
-
# Choose your destiny? (
|
816
|
+
# Choose your destiny? (Use ↑/↓ and ←/→ arrow keys, press Enter to select)
|
699
817
|
# > Scorpion
|
700
818
|
# Kano
|
701
819
|
# Jax
|
702
820
|
```
|
703
821
|
|
704
|
-
#### 2.6.
|
822
|
+
#### 2.6.2.5 `:per_page`
|
705
823
|
|
706
824
|
By default the menu is paginated if selection grows beyond `6` items. To change this setting use `:per_page` configuration.
|
707
825
|
|
708
826
|
```ruby
|
709
|
-
letters = (
|
827
|
+
letters = ("A".."Z").to_a
|
710
828
|
prompt.select("Choose your letter?", letters, per_page: 4)
|
711
829
|
# =>
|
712
830
|
# Which letter? (Use ↑/↓ and ←/→ arrow keys, press Enter to select)
|
@@ -716,35 +834,41 @@ prompt.select("Choose your letter?", letters, per_page: 4)
|
|
716
834
|
# D
|
717
835
|
```
|
718
836
|
|
719
|
-
You can also customise page navigation text using `:
|
837
|
+
You can also customise page navigation text using `:help` option:
|
720
838
|
```ruby
|
721
|
-
letters = (
|
839
|
+
letters = ("A".."Z").to_a
|
722
840
|
prompt.select("Choose your letter?") do |menu|
|
723
841
|
menu.per_page 4
|
724
|
-
menu.
|
842
|
+
menu.help "(Wiggle thy finger up/down and left/right to see more)"
|
725
843
|
menu.choices letters
|
726
844
|
end
|
845
|
+
# =>
|
846
|
+
# Which letter? (Wiggle thy finger up/down and left/right to see more)
|
847
|
+
# ‣ A
|
848
|
+
# B
|
849
|
+
# C
|
850
|
+
# D
|
727
851
|
```
|
728
852
|
|
729
|
-
#### 2.6.2.
|
853
|
+
#### 2.6.2.6 `:disabled`
|
730
854
|
|
731
855
|
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:
|
732
856
|
|
733
857
|
```ruby
|
734
858
|
warriors = [
|
735
|
-
|
736
|
-
|
737
|
-
{ name:
|
738
|
-
|
739
|
-
|
740
|
-
|
859
|
+
"Scorpion",
|
860
|
+
"Kano",
|
861
|
+
{ name: "Goro", disabled: "(injury)" },
|
862
|
+
"Jax",
|
863
|
+
"Kitana",
|
864
|
+
"Raiden"
|
741
865
|
]
|
742
866
|
```
|
743
867
|
|
744
868
|
The disabled choice will be displayed with a cross `✘` character next to it and followed by an explanation:
|
745
869
|
|
746
870
|
```ruby
|
747
|
-
prompt.select(
|
871
|
+
prompt.select("Choose your destiny?", warriors)
|
748
872
|
# =>
|
749
873
|
# Choose your destiny? (Use ↑/↓ arrow keys, press Enter to select)
|
750
874
|
# ‣ Scorpion
|
@@ -755,13 +879,13 @@ prompt.select('Choose your destiny?', warriors)
|
|
755
879
|
# Raiden
|
756
880
|
```
|
757
881
|
|
758
|
-
#### 2.6.2.
|
882
|
+
#### 2.6.2.7 `:filter`
|
759
883
|
|
760
884
|
To activate dynamic list searching on letter/number key presses use `:filter` option:
|
761
885
|
|
762
886
|
```ruby
|
763
887
|
warriors = %w(Scorpion Kano Jax Kitana Raiden)
|
764
|
-
prompt.select(
|
888
|
+
prompt.select("Choose your destiny?", warriors, filter: true)
|
765
889
|
# =>
|
766
890
|
# Choose your destiny? (Use ↑/↓ arrow keys, press Enter to select, and letter keys to filter)
|
767
891
|
# ‣ Scorpion
|
@@ -830,11 +954,12 @@ prompt.multi_select("Select drinks?") do |menu|
|
|
830
954
|
end
|
831
955
|
```
|
832
956
|
|
833
|
-
To mark choice(s) as selected use the `default` option with index(s) of the
|
957
|
+
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):
|
834
958
|
|
835
959
|
```ruby
|
836
960
|
prompt.multi_select("Select drinks?") do |menu|
|
837
961
|
menu.default 2, 5
|
962
|
+
# or menu.default :beer, :whisky
|
838
963
|
|
839
964
|
menu.choice :vodka, {score: 10}
|
840
965
|
menu.choice :beer, {score: 20}
|
@@ -851,11 +976,21 @@ end
|
|
851
976
|
# ‣ ⬢ bourbon
|
852
977
|
```
|
853
978
|
|
979
|
+
#### 2.6.3.1 `:cycle`
|
980
|
+
|
981
|
+
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:
|
982
|
+
|
983
|
+
```ruby
|
984
|
+
prompt.multi_select("Select drinks?", %w(vodka beer wine), cycle: true)
|
985
|
+
```
|
986
|
+
|
987
|
+
#### 2.6.3.2 `:enum`
|
988
|
+
|
854
989
|
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.
|
855
990
|
|
856
991
|
```ruby
|
857
992
|
prompt.multi_select("Select drinks?") do |menu|
|
858
|
-
menu.enum
|
993
|
+
menu.enum ")"
|
859
994
|
|
860
995
|
menu.choice :vodka, {score: 10}
|
861
996
|
menu.choice :beer, {score: 20}
|
@@ -879,17 +1014,13 @@ And when you press enter you will see the following selected:
|
|
879
1014
|
# => [{score: 20}, {score: 50}]
|
880
1015
|
```
|
881
1016
|
|
882
|
-
|
1017
|
+
#### 2.6.3.3 `:help`
|
883
1018
|
|
884
|
-
|
885
|
-
prompt.multi_select("Select drinks?", %w(vodka beer wine), cycle: true)
|
886
|
-
```
|
887
|
-
|
888
|
-
You can configure help message and/or marker like so
|
1019
|
+
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`:
|
889
1020
|
|
890
1021
|
```ruby
|
891
1022
|
choices = {vodka: 1, beer: 2, wine: 3, whisky: 4, bourbon: 5}
|
892
|
-
prompt.multi_select("Select drinks?", choices, help:
|
1023
|
+
prompt.multi_select("Select drinks?", choices, help: "Press beer can against keyboard", show_help: :always)
|
893
1024
|
# =>
|
894
1025
|
# Select drinks? (Press beer can against keyboard)"
|
895
1026
|
# ‣ ⬡ vodka
|
@@ -899,10 +1030,12 @@ prompt.multi_select("Select drinks?", choices, help: 'Press beer can against key
|
|
899
1030
|
# ⬡ bourbon
|
900
1031
|
```
|
901
1032
|
|
1033
|
+
#### 2.6.3.4 `:per_page`
|
1034
|
+
|
902
1035
|
By default the menu is paginated if selection grows beyond `6` items. To change this setting use `:per_page` configuration.
|
903
1036
|
|
904
1037
|
```ruby
|
905
|
-
letters = (
|
1038
|
+
letters = ("A".."Z").to_a
|
906
1039
|
prompt.multi_select("Choose your letter?", letters, per_page: 4)
|
907
1040
|
# =>
|
908
1041
|
# 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)
|
|
912
1045
|
# ⬡ D
|
913
1046
|
```
|
914
1047
|
|
915
|
-
#### 2.6.3.
|
1048
|
+
#### 2.6.3.5 `:disabled`
|
916
1049
|
|
917
1050
|
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:
|
918
1051
|
|
919
1052
|
```ruby
|
920
1053
|
drinks = [
|
921
|
-
|
922
|
-
{name:
|
923
|
-
|
924
|
-
{name:
|
925
|
-
|
926
|
-
|
1054
|
+
"bourbon",
|
1055
|
+
{name: "sake", disabled: "(out of stock)"},
|
1056
|
+
"vodka",
|
1057
|
+
{name: "beer", disabled: "(out of stock)"},
|
1058
|
+
"wine",
|
1059
|
+
"whisky"
|
927
1060
|
]
|
928
1061
|
```
|
929
1062
|
|
930
1063
|
The disabled choice will be displayed with a cross `✘` character next to it and followed by an explanation:
|
931
1064
|
|
932
1065
|
```ruby
|
933
|
-
prompt.multi_select(
|
1066
|
+
prompt.multi_select("Choose your favourite drink?", drinks)
|
934
1067
|
# =>
|
935
1068
|
# Choose your favourite drink? (Use ↑/↓ arrow keys, press Space to select and Enter to finish)
|
936
1069
|
# ‣ ⬡ bourbon
|
@@ -941,7 +1074,7 @@ prompt.multi_select('Choose your favourite drink?', drinks)
|
|
941
1074
|
# ⬡ whisky
|
942
1075
|
```
|
943
1076
|
|
944
|
-
#### 2.6.3.
|
1077
|
+
#### 2.6.3.6 `:echo`
|
945
1078
|
|
946
1079
|
To control whether the selected items are shown on the question
|
947
1080
|
header use the :echo option:
|
@@ -958,7 +1091,7 @@ prompt.multi_select("Select drinks?", choices, echo: false)
|
|
958
1091
|
# ‣ ⬢ 5) bourbon
|
959
1092
|
```
|
960
1093
|
|
961
|
-
#### 2.6.3.
|
1094
|
+
#### 2.6.3.7 `:filter`
|
962
1095
|
|
963
1096
|
To activate dynamic list filtering on letter/number typing, use the :filter option:
|
964
1097
|
|
@@ -988,9 +1121,25 @@ If the user changes or deletes a filter, the choices previously selected remain
|
|
988
1121
|
|
989
1122
|
The `filter` option is not compatible with `enum`.
|
990
1123
|
|
991
|
-
#### 2.6.3.
|
1124
|
+
#### 2.6.3.8 `:min`
|
1125
|
+
|
1126
|
+
To force the minimum number of choices an user must select, use the `:min` option:
|
1127
|
+
|
1128
|
+
```ruby
|
1129
|
+
choices = %w(vodka beer wine whisky bourbon)
|
1130
|
+
prompt.multi_select("Select drinks?", choices, min: 3)
|
1131
|
+
# =>
|
1132
|
+
# Select drinks? (min. 3) vodka, beer
|
1133
|
+
# ⬢ vodka
|
1134
|
+
# ⬢ beer
|
1135
|
+
# ⬡ wine
|
1136
|
+
# ⬡ wiskey
|
1137
|
+
# ‣ ⬡ bourbon
|
1138
|
+
```
|
1139
|
+
|
1140
|
+
#### 2.6.3.9 `:max`
|
992
1141
|
|
993
|
-
To limit the number of choices an user can select, use `:max` option:
|
1142
|
+
To limit the number of choices an user can select, use the `:max` option:
|
994
1143
|
|
995
1144
|
```ruby
|
996
1145
|
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
|
|
1010
1159
|
|
1011
1160
|
```ruby
|
1012
1161
|
choices = %w(emacs nano vim)
|
1013
|
-
prompt.enum_select("Select an editor?")
|
1162
|
+
prompt.enum_select("Select an editor?", choices)
|
1014
1163
|
# =>
|
1015
1164
|
#
|
1016
1165
|
# Select an editor?
|
@@ -1025,9 +1174,9 @@ Similar to `select` and `multi_select`, you can provide question options through
|
|
1025
1174
|
```ruby
|
1026
1175
|
choices = %w(nano vim emacs)
|
1027
1176
|
prompt.enum_select("Select an editor?") do |menu|
|
1028
|
-
menu.choice :nano,
|
1029
|
-
menu.choice :vim,
|
1030
|
-
menu.choice :emacs,
|
1177
|
+
menu.choice :nano, "/bin/nano"
|
1178
|
+
menu.choice :vim, "/usr/bin/vim"
|
1179
|
+
menu.choice :emacs, "/usr/bin/emacs"
|
1031
1180
|
end
|
1032
1181
|
# =>
|
1033
1182
|
#
|
@@ -1040,17 +1189,18 @@ end
|
|
1040
1189
|
# Select an editor? /bin/nano
|
1041
1190
|
```
|
1042
1191
|
|
1043
|
-
You can change the indexed numbers by passing `enum` option
|
1192
|
+
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:
|
1044
1193
|
|
1045
1194
|
```ruby
|
1046
1195
|
choices = %w(nano vim emacs)
|
1047
1196
|
prompt.enum_select("Select an editor?") do |menu|
|
1048
1197
|
menu.default 2
|
1049
|
-
menu.
|
1198
|
+
# or menu.defualt "/usr/bin/vim"
|
1199
|
+
menu.enum "."
|
1050
1200
|
|
1051
|
-
menu.choice :nano,
|
1052
|
-
menu.choice :vim,
|
1053
|
-
menu.choice :emacs,
|
1201
|
+
menu.choice :nano, "/bin/nano"
|
1202
|
+
menu.choice :vim, "/usr/bin/vim"
|
1203
|
+
menu.choice :emacs, "/usr/bin/emacs"
|
1054
1204
|
end
|
1055
1205
|
# =>
|
1056
1206
|
#
|
@@ -1068,7 +1218,7 @@ end
|
|
1068
1218
|
By default the menu is paginated if selection grows beyond `6` items. To change this setting use `:per_page` configuration.
|
1069
1219
|
|
1070
1220
|
```ruby
|
1071
|
-
letters = (
|
1221
|
+
letters = ("A".."Z").to_a
|
1072
1222
|
prompt.enum_select("Choose your letter?", letters, per_page: 4)
|
1073
1223
|
# =>
|
1074
1224
|
# Which letter?
|
@@ -1086,10 +1236,10 @@ To make a choice unavailable use the `:disabled` option and, if you wish, as val
|
|
1086
1236
|
|
1087
1237
|
```ruby
|
1088
1238
|
choices = [
|
1089
|
-
{name: "Emacs", disabled:
|
1239
|
+
{name: "Emacs", disabled: "(not installed)"},
|
1090
1240
|
"Atom",
|
1091
1241
|
"GNU nano",
|
1092
|
-
{name: "Notepad++", disabled:
|
1242
|
+
{name: "Notepad++", disabled: "(not installed)"},
|
1093
1243
|
"Sublime",
|
1094
1244
|
"Vim"
|
1095
1245
|
]
|
@@ -1099,7 +1249,7 @@ The disabled choice will be displayed with a cross ✘ character next to it and
|
|
1099
1249
|
|
1100
1250
|
|
1101
1251
|
```ruby
|
1102
|
-
prompt.enum_select(
|
1252
|
+
prompt.enum_select("Select an editor", choices)
|
1103
1253
|
# =>
|
1104
1254
|
# Select an editor
|
1105
1255
|
# ✘ 1) Emacs (not installed)
|
@@ -1120,16 +1270,16 @@ As first argument `expand` takes the message to display and as a second an array
|
|
1120
1270
|
```ruby
|
1121
1271
|
choices = [
|
1122
1272
|
{
|
1123
|
-
key:
|
1124
|
-
name:
|
1273
|
+
key: "y",
|
1274
|
+
name: "overwrite this file",
|
1125
1275
|
value: :yes
|
1126
1276
|
}, {
|
1127
|
-
key:
|
1128
|
-
name:
|
1277
|
+
key: "n",
|
1278
|
+
name: "do not overwrite this file",
|
1129
1279
|
value: :no
|
1130
1280
|
}, {
|
1131
|
-
key:
|
1132
|
-
name:
|
1281
|
+
key: "q",
|
1282
|
+
name: "quit; do not overwrite this file ",
|
1133
1283
|
value: :quit
|
1134
1284
|
}
|
1135
1285
|
]
|
@@ -1138,19 +1288,19 @@ choices = [
|
|
1138
1288
|
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:
|
1139
1289
|
|
1140
1290
|
```ruby
|
1141
|
-
prompt.expand(
|
1142
|
-
q.choice key:
|
1143
|
-
q.choice key:
|
1144
|
-
q.choice key:
|
1145
|
-
q.choice key:
|
1146
|
-
q.choice key:
|
1291
|
+
prompt.expand("Overwrite Gemfile?") do |q|
|
1292
|
+
q.choice key: "y", name: "Overwrite" do :ok end
|
1293
|
+
q.choice key: "n", name: "Skip", value: :no
|
1294
|
+
q.choice key: "a", name: "Overwrite all", value: :all
|
1295
|
+
q.choice key: "d", name: "Show diff", value: :diff
|
1296
|
+
q.choice key: "q", name: "Quit", value: :quit
|
1147
1297
|
end
|
1148
1298
|
```
|
1149
1299
|
|
1150
1300
|
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.
|
1151
1301
|
|
1152
1302
|
```ruby
|
1153
|
-
prompt.expand(
|
1303
|
+
prompt.expand("Overwrite Gemfile?", choices)
|
1154
1304
|
# =>
|
1155
1305
|
# Overwrite Gemfile? (enter "h" for help) [y,n,q,h]
|
1156
1306
|
```
|
@@ -1180,7 +1330,7 @@ Run `examples/expand.rb` to see the prompt in action.
|
|
1180
1330
|
To show hint by default use `:auto_hint` option:
|
1181
1331
|
|
1182
1332
|
```ruby
|
1183
|
-
prompt.expand(
|
1333
|
+
prompt.expand("Overwrite Gemfile?", choices, auto_hint: true)
|
1184
1334
|
# =>
|
1185
1335
|
# Overwrite Gemfile? (enter "h" for help) [y,n,q,h]
|
1186
1336
|
# >> overwrite this file
|
@@ -1194,14 +1344,14 @@ For example to gather some contact information do:
|
|
1194
1344
|
|
1195
1345
|
```ruby
|
1196
1346
|
prompt.collect do
|
1197
|
-
key(:name).ask(
|
1347
|
+
key(:name).ask("Name?")
|
1198
1348
|
|
1199
|
-
key(:age).ask(
|
1349
|
+
key(:age).ask("Age?", convert: :int)
|
1200
1350
|
|
1201
1351
|
key(:address) do
|
1202
|
-
key(:street).ask(
|
1203
|
-
key(:city).ask(
|
1204
|
-
key(:zip).ask(
|
1352
|
+
key(:street).ask("Street?", required: true)
|
1353
|
+
key(:city).ask("City?")
|
1354
|
+
key(:zip).ask("Zip?", validate: /\A\d{3}\Z/)
|
1205
1355
|
end
|
1206
1356
|
end
|
1207
1357
|
# =>
|
@@ -1210,17 +1360,17 @@ end
|
|
1210
1360
|
|
1211
1361
|
In order to collect _mutliple values_ for a given key in a loop, chain `values` onto the `key` desired:
|
1212
1362
|
|
1213
|
-
```
|
1363
|
+
```ruby
|
1214
1364
|
result = prompt.collect do
|
1215
|
-
key(:name).ask(
|
1365
|
+
key(:name).ask("Name?")
|
1216
1366
|
|
1217
|
-
key(:age).ask(
|
1367
|
+
key(:age).ask("Age?", convert: :int)
|
1218
1368
|
|
1219
1369
|
while prompt.yes?("continue?")
|
1220
1370
|
key(:addresses).values do
|
1221
|
-
key(:street).ask(
|
1222
|
-
key(:city).ask(
|
1223
|
-
key(:zip).ask(
|
1371
|
+
key(:street).ask("Street?", required: true)
|
1372
|
+
key(:city).ask("City?")
|
1373
|
+
key(:zip).ask("Zip?", validate: /\A\d{3}\Z/)
|
1224
1374
|
end
|
1225
1375
|
end
|
1226
1376
|
end
|
@@ -1240,7 +1390,7 @@ end
|
|
1240
1390
|
To suggest possible matches for the user input use `suggest` method like so:
|
1241
1391
|
|
1242
1392
|
```ruby
|
1243
|
-
prompt.suggest(
|
1393
|
+
prompt.suggest("sta", ["stage", "stash", "commit", "branch"])
|
1244
1394
|
# =>
|
1245
1395
|
# Did you mean one of these?
|
1246
1396
|
# stage
|
@@ -1251,7 +1401,7 @@ To customize query text presented pass `:single_text` and `:plural_text` options
|
|
1251
1401
|
|
1252
1402
|
```ruby
|
1253
1403
|
possible = %w(status stage stash commit branch blame)
|
1254
|
-
prompt.suggest(
|
1404
|
+
prompt.suggest("b", possible, indent: 4, single_text: "Perhaps you meant?")
|
1255
1405
|
# =>
|
1256
1406
|
# Perhaps you meant?
|
1257
1407
|
# blame
|
@@ -1259,33 +1409,51 @@ prompt.suggest('b', possible, indent: 4, single_text: 'Perhaps you meant?')
|
|
1259
1409
|
|
1260
1410
|
### 2.10 slider
|
1261
1411
|
|
1262
|
-
If you
|
1412
|
+
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.
|
1263
1413
|
|
1264
|
-
|
1414
|
+
For integers, you can set `:min`(defaults to 0), `:max` and `:step`(defaults to 1) options to configure slider range:
|
1265
1415
|
|
1266
1416
|
```ruby
|
1267
|
-
prompt.slider(
|
1417
|
+
prompt.slider("Volume", min: 0, max: 100, step: 5)
|
1268
1418
|
# =>
|
1269
1419
|
# Volume ──────────●────────── 50
|
1270
|
-
# (Use arrow keys, press Enter to select)
|
1420
|
+
# (Use ←/→ arrow keys, press Enter to select)
|
1421
|
+
```
|
1422
|
+
|
1423
|
+
For everything else, you can provide an array of your desired choices:
|
1424
|
+
|
1425
|
+
```ruby
|
1426
|
+
prompt.slider("Letter", ('a'..'z').to_a)
|
1427
|
+
# =>
|
1428
|
+
# Letter ────────────●───────────── m
|
1429
|
+
# (Use ←/→ arrow keys, press Enter to select)
|
1271
1430
|
```
|
1272
1431
|
|
1273
1432
|
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:
|
1274
1433
|
|
1275
1434
|
```ruby
|
1276
|
-
prompt.slider(
|
1435
|
+
prompt.slider("Volume", max: 100, step: 5, default: 75)
|
1277
1436
|
# =>
|
1278
1437
|
# Volume ───────────────●────── 75
|
1279
|
-
# (Use arrow keys, press Enter to select)
|
1438
|
+
# (Use ←/→ arrow keys, press Enter to select)
|
1439
|
+
```
|
1440
|
+
|
1441
|
+
You can also select the default value by name:
|
1442
|
+
|
1443
|
+
```ruby
|
1444
|
+
prompt.slider("Letter", ('a'..'z').to_a, default: 'q')
|
1445
|
+
# =>
|
1446
|
+
# Letter ──────────────────●─────── q
|
1447
|
+
# (Use ←/→ arrow keys, press Enter to select)
|
1280
1448
|
```
|
1281
1449
|
|
1282
1450
|
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`:
|
1283
1451
|
|
1284
1452
|
```ruby
|
1285
|
-
prompt.slider(
|
1453
|
+
prompt.slider("Volume", max: 100, step: 5, default: 75, format: "|:slider| %d%%")
|
1286
1454
|
# =>
|
1287
1455
|
# Volume |───────────────●──────| 75%
|
1288
|
-
# (Use arrow keys, press Enter to select)
|
1456
|
+
# (Use ←/→ arrow keys, press Enter to select)
|
1289
1457
|
```
|
1290
1458
|
|
1291
1459
|
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
|
|
1294
1462
|
prompt.slider("Volume", max: 10, step: 0.5, default: 5, format: "|:slider| %.1f")
|
1295
1463
|
# =>
|
1296
1464
|
# Volume |───────────────●──────| 7.5
|
1297
|
-
# (Use arrow keys, press Enter to select)
|
1465
|
+
# (Use ←/→ arrow keys, press Enter to select)
|
1466
|
+
```
|
1467
|
+
|
1468
|
+
You can alternatively provide a proc/lambda to customize your formatting even further:
|
1469
|
+
|
1470
|
+
```ruby
|
1471
|
+
slider_format = -> (slider, value) { "|#{slider}| #{value.zero? ? "muted" : "%.1f"}" % value }
|
1472
|
+
prompt.slider("Volume", max: 10, step: 0.5, default: 0, format: slider_format)
|
1473
|
+
# =>
|
1474
|
+
# Volume |●─────────────────────| muted
|
1475
|
+
# (Use ←/→ arrow keys, press Enter to select)
|
1298
1476
|
```
|
1299
1477
|
|
1300
1478
|
If you wish to change the slider handle and the slider range display use `:symbols` option:
|
1301
1479
|
|
1302
1480
|
```ruby
|
1303
|
-
prompt.slider("Volume", max: 100, step: 5, default: 75, symbols: {bullet:
|
1481
|
+
prompt.slider("Volume", max: 100, step: 5, default: 75, symbols: {bullet: "x", line: "_"})
|
1304
1482
|
# =>
|
1305
1483
|
# Volume _______________x______ 75%
|
1306
|
-
# (Use arrow keys, press Enter to select)
|
1484
|
+
# (Use ←/→ arrow keys, press Enter to select)
|
1485
|
+
```
|
1486
|
+
|
1487
|
+
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`:
|
1488
|
+
|
1489
|
+
```ruby
|
1490
|
+
prompt.slider("Volume", max: 10, default: 7, help: "(Move arrows left and right to set value)", show_help: :always)
|
1491
|
+
# =>
|
1492
|
+
# Volume ───────────────●────── 7
|
1493
|
+
# (Move arrows left and right to set value)
|
1307
1494
|
```
|
1308
1495
|
|
1309
1496
|
Slider can be configured through DSL as well:
|
1310
1497
|
|
1311
1498
|
```ruby
|
1312
|
-
prompt.slider(
|
1499
|
+
prompt.slider("What size?") do |range|
|
1313
1500
|
range.max 100
|
1314
1501
|
range.step 5
|
1315
1502
|
range.default 75
|
1316
|
-
range.format "|:slider| %d
|
1503
|
+
range.format "|:slider| %d%%"
|
1317
1504
|
end
|
1318
1505
|
# =>
|
1319
1506
|
# Volume |───────────────●──────| 75%
|
1320
|
-
# (Use arrow keys, press Enter to select)
|
1507
|
+
# (Use ←/→ arrow keys, press Enter to select)
|
1321
1508
|
```
|
1322
1509
|
|
1510
|
+
```ruby
|
1511
|
+
prompt.slider("What letter?") do |range|
|
1512
|
+
range.choices ('a'..'z').to_a
|
1513
|
+
range.format "|:slider| %s"
|
1514
|
+
range.default 'q'
|
1515
|
+
end
|
1516
|
+
# =>
|
1517
|
+
# What letter? |──────────────────●───────| q
|
1518
|
+
# (Use ←/→ arrow keys, press Enter to select)
|
1519
|
+
```
|
1520
|
+
|
1521
|
+
|
1323
1522
|
### 2.11 say
|
1324
1523
|
|
1325
1524
|
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
|
|
1375
1574
|
|
1376
1575
|
```ruby
|
1377
1576
|
prompt.on(:keypress) do |event|
|
1378
|
-
if event.value ==
|
1577
|
+
if event.value == "j"
|
1379
1578
|
prompt.trigger(:keydown)
|
1380
1579
|
end
|
1381
1580
|
|
1382
|
-
if event.value ==
|
1581
|
+
if event.value == "k"
|
1383
1582
|
prompt.trigger(:keyup)
|
1384
1583
|
end
|
1385
1584
|
end
|
@@ -1415,7 +1614,7 @@ The available events are:
|
|
1415
1614
|
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:
|
1416
1615
|
|
1417
1616
|
```ruby
|
1418
|
-
prompt = TTY::Prompt.new(symbols: {marker:
|
1617
|
+
prompt = TTY::Prompt.new(symbols: {marker: ">"})
|
1419
1618
|
```
|
1420
1619
|
|
1421
1620
|
The following symbols can be overwritten:
|
@@ -1437,16 +1636,37 @@ The following symbols can be overwritten:
|
|
1437
1636
|
|
1438
1637
|
### 3.2 `:active_color`
|
1439
1638
|
|
1440
|
-
All prompt types support `:active_color` option.
|
1639
|
+
All prompt types support `:active_color` option. By default it's set to `:green` value.
|
1640
|
+
|
1641
|
+
The `select`, `multi_select`, `enum_select` and `expand` prompts use the active color to highlight the currently selected choice.
|
1642
|
+
|
1643
|
+
The answer provided by the user is also highlighted with the active color.
|
1644
|
+
|
1645
|
+
This `:active_color` as value accepts either a color symbol or callable object.
|
1646
|
+
|
1647
|
+
For example, to change all prompts active color to `:cyan` do:
|
1441
1648
|
|
1442
1649
|
```ruby
|
1443
1650
|
prompt = TTY::Prompt.new(active_color: :cyan)
|
1444
1651
|
```
|
1445
1652
|
|
1446
|
-
|
1653
|
+
You could also use `pastel`:
|
1447
1654
|
|
1448
1655
|
```ruby
|
1449
|
-
|
1656
|
+
notice = Pastel.new.cyan.on_blue.detach
|
1657
|
+
prompt = TTY::Prompt.new(active_color: notice)
|
1658
|
+
````
|
1659
|
+
|
1660
|
+
Or use coloring of your own choice:
|
1661
|
+
|
1662
|
+
```
|
1663
|
+
prompt = TTY::Prompt.new(active_color: ->(str) { my-color-gem(str) })
|
1664
|
+
```
|
1665
|
+
|
1666
|
+
This option can be applied either globally for all prompts or individually:
|
1667
|
+
|
1668
|
+
```ruby
|
1669
|
+
prompt.select("What size?", %w(Large Medium Small), active_color: :cyan)
|
1450
1670
|
```
|
1451
1671
|
|
1452
1672
|
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
|
|
1456
1676
|
If you wish to disable coloring for a prompt simply pass `:enable_color` option
|
1457
1677
|
|
1458
1678
|
```ruby
|
1459
|
-
prompt = TTY::Prompt.new(enable_color:
|
1679
|
+
prompt = TTY::Prompt.new(enable_color: false)
|
1460
1680
|
```
|
1461
1681
|
|
1462
1682
|
### 3.4 `:help_color`
|
1463
1683
|
|
1464
|
-
|
1684
|
+
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.
|
1685
|
+
|
1686
|
+
Prompts such as `select`, `multi_select`, `expand` support `:help_color`. This option can be applied either globally for all prompts or individually.
|
1687
|
+
|
1688
|
+
The `:help_color` option as value accepts either a color symbol or callable object.
|
1689
|
+
|
1690
|
+
For example, to change all prompts help color to `:cyan` do:
|
1465
1691
|
|
1466
1692
|
```ruby
|
1467
1693
|
prompt = TTY::Prompt.new(help_color: :cyan)
|
1468
1694
|
```
|
1469
1695
|
|
1470
|
-
|
1696
|
+
You could also use `pastel`:
|
1471
1697
|
|
1472
1698
|
```ruby
|
1473
|
-
|
1699
|
+
notice = Pastel.new.cyan.on_blue.detach
|
1700
|
+
prompt = TTY::Prompt.new(help_color: notice)
|
1701
|
+
````
|
1702
|
+
|
1703
|
+
Or use coloring of your own choice:
|
1704
|
+
|
1705
|
+
```ruby
|
1706
|
+
prompt = TTY::Prompt.new(help_color: ->(str) { my-color-gem(str) })
|
1474
1707
|
```
|
1475
1708
|
|
1709
|
+
Or configure `:help_color` for an individual prompt:
|
1710
|
+
|
1711
|
+
```ruby
|
1712
|
+
prompt.select("What size?", %w(Large Medium Small), help_color: :cyan)
|
1713
|
+
```
|
1714
|
+
|
1715
|
+
Please [see pastel](https://github.com/piotrmurach/pastel#3-supported-colors) for all supported colors.
|
1716
|
+
|
1476
1717
|
### 3.5 `:interrupt`
|
1477
1718
|
|
1478
1719
|
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:
|
1479
1720
|
|
1480
1721
|
* `:signal` - sends interrupt signal
|
1481
|
-
* `:exit` -
|
1722
|
+
* `:exit` - exits with status code
|
1482
1723
|
* `:noop` - skips handler
|
1483
1724
|
* custom proc
|
1484
1725
|
|
@@ -1493,10 +1734,21 @@ prompt = TTY::Prompt.new(interrupt: :signal)
|
|
1493
1734
|
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:
|
1494
1735
|
|
1495
1736
|
```ruby
|
1496
|
-
prompt = TTY::Prompt.new(prefix:
|
1737
|
+
prompt = TTY::Prompt.new(prefix: "[?] ")
|
1497
1738
|
```
|
1498
1739
|
|
1499
|
-
### 3.7 `:
|
1740
|
+
### 3.7 `:quiet`
|
1741
|
+
|
1742
|
+
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.
|
1743
|
+
|
1744
|
+
```ruby
|
1745
|
+
# global
|
1746
|
+
prompt = TTY::Prompt.new(quiet: true)
|
1747
|
+
# single prompt
|
1748
|
+
prompt.select("What is your favorite color?", %w(blue yellow orange))
|
1749
|
+
````
|
1750
|
+
|
1751
|
+
### 3.8 `:track_history`
|
1500
1752
|
|
1501
1753
|
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:
|
1502
1754
|
|