highline_wrapper 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0454ae57461089fa8b01bd5174e89e8eb71dc41c110a82bb86f4473f345bafdf
-  data.tar.gz: 34dba9a54d461b365da6de34bbd1c20611bec926df54699c2673306a9eb82828
+  metadata.gz: 2ce70d5eeb141d2b2440550b66335dc2e94a69acd4a0a214fea5dd78506b0bf8
+  data.tar.gz: e88f0e2c78bba7f92aec919a21326d75ac84b324c5ff3c0c2b5177346605bb62
 SHA512:
-  metadata.gz: 513c0869cf6ac26663fcab9e65cb01897875fcdd4a9d31ff9ff890728a9004a26f1503c94c374e363d99b6e1649931427c121f4a10638120cbec11e9efdd78a8
-  data.tar.gz: 85e805046f5d586303ea0286ab810d974d6a3466e57e0c794f3d61771e9a67cebf17039100490841c1716d16b79b9c88b1a0c62bea818ec73c6bdd660aaecc24
+  metadata.gz: ae702cfaa01941f91f445145af9f4143a234f3ef9c41cec601454fa75a1b0268b9ffa70a2384b236472b916281e2dac38c8721791c5b1d7c60029b1b135949f2
+  data.tar.gz: 3891869ced3281e666861618dae0f43f81eff9f62c1a8cfd26d4e67758085585fe33595918b484fdf67fdf13ed1b7e013de82730229bf8c8d4fed39e5afc0981

data/Gemfile.lock

@@ -0,0 +1,100 @@
+PATH
+  remote: .
+  specs:
+    highline_wrapper (1.0.0)
+      highline (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.8)
+    diff-lcs (1.4.4)
+    faker (2.16.0)
+      i18n (>= 1.6, < 2)
+    ffi (1.14.2)
+    formatador (0.2.5)
+    guard (2.16.2)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    highline (2.0.3)
+    i18n (1.8.9)
+      concurrent-ruby (~> 1.0)
+    listen (3.4.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    lumberjack (1.2.8)
+    method_source (1.0.0)
+    nenv (0.3.0)
+    notiffany (0.1.3)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    parallel (1.20.1)
+    parser (3.0.0.0)
+      ast (~> 2.4.1)
+    pry (0.14.0)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    rainbow (3.0.0)
+    rake (13.0.3)
+    rb-fsevent (0.10.4)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    regexp_parser (2.1.1)
+    rexml (3.2.4)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+    rubocop (1.11.0)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.2.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.4.1)
+      parser (>= 2.7.1.5)
+    ruby-progressbar (1.11.0)
+    shellany (0.0.1)
+    thor (1.1.0)
+    unicode-display_width (2.0.0)
+
+PLATFORMS
+  x86_64-darwin-20
+
+DEPENDENCIES
+  bundler (~> 2.2)
+  faker (~> 2.15)
+  guard-rspec (~> 4.3)
+  highline_wrapper!
+  pry (~> 0.13)
+  rake (~> 13.0)
+  rspec (~> 3.9)
+  rubocop (~> 1.10)
+
+BUNDLED WITH
+   2.2.4

data/README.md

@@ -27,7 +27,7 @@ Or install it yourself as:
 gem install highline_wrapper
 ```
 
-### Usage
+## Usage
 
 Once this gem is installed, you can then initiate a new `HighlineWrapper` object:
 
@@ -41,53 +41,309 @@ Then, add this to the top of your file (or to your gem):
 require 'highline_wrapper'
 ```
 
-Then, you can call its questions to receive answers:
+Then, you can call its questions to receive answers. There's several configuration options for each type of question. Look below for the different options for each type of question, and what they each return.
+
+### Open-ended questions
+
+Question configuration options:
+* `secret`: defaults to `false`
+* `default`: defaults to `''`
+* `required`: defaults to `false`
+
+<details><summary>Examples</summary>
 
 ```ruby
 > HighlineWrapper.new.ask('What is your favorite number?')
 What is your favorite number?
 four
+
 => "four"
 
+> HighlineWrapper.new.ask('What is your favorite number?', {required: true})
+What is your favorite number?
+
+This question is required.
+
+What is your favorite number?
+
+This question is required.
+
+What is your favorite number?
+2
+
+=> "2"
+
+> HighlineWrapper.new.ask('What is your favorite color?')
+What is your favorite color?
+
+=> ""
+
+> HighlineWrapper.new.ask('What is your favorite color?', {default: 'orange'})
+What is your favorite color?
+
+=> "orange"
+
+> HighlineWrapper.new.ask('Please type your private token:', {secret: true})
+Please type your private token?
+****************
+
+=> "MY-PRIVATE-TOKEN"
+
+> HighlineWrapper.new.ask('What is your private token?', {secret: true, required: true})
+What is your private token?
+
+This question is required.
+
+What is your private token?
+
+This question is required.
+
+What is your private token?
+
+This question is required.
+
+What is your private token?
+****************
+
+=> "MY-PRIVATE-TOKEN"
+```
+
+</details>
+
+### Yes/No questions
+
+Question configuration options:
+* `default`: defaults to `true` (aka 'yes')
+* `required`: defaults to `false`
+
+<details><summary>Examples</summary>
+
+```ruby
 > HighlineWrapper.new.ask_yes_no('Do you like Ruby?')
 Do you like Ruby?
 no
+
 => false
 
 > HighlineWrapper.new.ask_yes_no('Do you like Ruby?')
 Do you like Ruby?
 yes
+
 => true
 
-HighlineWrapper.new.ask_multiple_choice('What is your favorite number of t
-hese?', ['one', 'two', 'three'])
+> HighlineWrapper.new.ask_yes_no('Do you like Ruby?', {default: false})
+Do you like Ruby?
+
+=> false
+
+> HighlineWrapper.new.ask_yes_no('Do you like Ruby?', {required: true})
+Do you like Ruby?
+
+This question is required.
+
+Do you like Ruby?
+No
+
+=> false
+
+> HighlineWrapper.new.ask_yes_no('Do you like Ruby?')
+Do you like Ruby?
+uh-huh
+
+This question is required.
+
+Do you like Ruby?
+YES
+
+=> true
+```
+
+</details>
+
+### Multiple choice question
+
+Question configuration options:
+* `with_index`: defaults to `false` (particularly handy when there may be duplicate-named but different items in the list—think Sally with ID 45 and Sally with ID 72)
+* `default`: defaults to `nil`
+* `required`: defaults to `false`
+
+Notes:
+* If `required` is `true`, the question will repeat until the user answers the question
+* If `required` is `true`, then the `default` value will be ignored (defaults to `nil`, but could be set to whatever and the code won't care... the question is required)
+* If `default` is `nil` and `required` is `false`, and the user skips the question, the answer will be `nil`
+* If `with_index` is `true`, a hash will be returned with the choice AND the index of the selection in the original `choices` array
+  * e.g. `{ value: 'c', index: 2 }`
+* If `with_index` is `false`, then a hash of one item will be returned
+  * e.g. `{ value: 'c' }`
+
+<details><summary>Examples</summary>
+
+```ruby
+> HighlineWrapper.new.ask_multiple_choice('What is your favorite number of these?', ['one', 'two', 'three'])
+What is your favorite number of these?
+1. one
+2. two
+3. three
+2
+
+=> {:value=>"two"}
+
+> HighlineWrapper.new.ask_multiple_choice('What is your favorite number of these?', ['one', 'two', 'three'], {with_index: true})
 What is your favorite number of these?
 1. one
 2. two
 3. three
 2
-=> "two"
 
-> HighlineWrapper.new.ask_checkbox("What are your favorite numbers of these?
-", ['one', 'two','three'])
+=> {:value=>"two", :index=>1}
+
+> HighlineWrapper.new.ask_multiple_choice('What is your favorite number of these?', ['one', 'two', 'three'], {with_index: true, default: 'one'})
+What is your favorite number of these?
+1. one
+2. two
+3. three
+
+=> {:value=>"one", :index=>0}
+
+> HighlineWrapper.new.ask_multiple_choice('What is your favorite number of these?', ['one', 'two', 'three'], {default: 'three', required: true})
+What is your favorite number of these?
+1. one
+2. two
+3. three
+
+This question is required.
+
+What is your favorite number of these?
+1. one
+2. two
+3. three
+
+This question is required.
+
+What is your favorite number of these?
+1. one
+2. two
+3. three
+2
+
+=> {:value=>"two"}
+
+> HighlineWrapper.new.ask_multiple_choice('What is your favorite number of these?', ['one', 'two', 'three'], {default: nil})
+What is your favorite number of these?
+1. one
+2. two
+3. three
+
+=> nil
+
+> HighlineWrapper.new.ask_multiple_choice('What is your favorite number of these?', ['one', 'two', 'three'], {default: nil, with_index: true})
+What is your favorite number of these?
+1. one
+2. two
+3. three
+
+=> nil
+```
+
+</details>
+
+### Multiple choice "checkbox" question
+
+Question configuration options:
+* `with_indexes`: defaults to `false` (particularly handy when there may be duplicate-named but different items in the list—think Sally with ID 45 and Sally with ID 72)
+* `defaults`: defaults to `[]`
+* `required`: defaults to `false`
+
+Notes:
+* If `required` is `true`, the question will repeat until the user answers the question
+* If `required` is `true`, then the `defaults` value will be ignored (this value is defaulting to `[]`, but could be set to whatever and the code won't care... the question is required)
+* If `defaults` is `[]` and `required` is `false`, then the method will return an empty array
+* If `with_indexes` is `true`, an array of hashes will be returned with the choice AND the index (of the selection in the original `choices` array) in each hash
+  * e.g. `[{ value: 'a', index: 0 }, { value: 'c', index: 2 }]`
+* If `with_indexes` is `false`, then an hashes will be returned where each hash only has a value
+  * e.g. `[{ value: 'a' }, { value: 'c' }]`
+
+<details><summary>Examples</summary>
+
+```ruby
+> HighlineWrapper.new.ask_checkbox("What are your favorite numbers of these?", ['one', 'two','three'])
 What are your favorite numbers of these?
 1. one
 2. two
 3. three
-1,3
-=> ["one", "three"]
+1, 3
+
+=> [{:value=>"one"}, {:value=>"three"}]
 
-> HighlineWrapper.new.ask_checkbox("What are your favorite numbers of these?
-", ['one', 'two','three'], with_indexes: true)
+> HighlineWrapper.new.ask_checkbox("What are your favorite numbers of these?", ['one', 'two','three'], {with_indexes: true})
 What are your favorite numbers of these?
 1. one
 2. two
 3. three
 1, 3
-=> [{:choice=>"one", :index=>0}, {:choice=>"three", :index=>2}]
+
+=> [{:value=>"one", :index=>0}, {:value=>"three", :index=>2}]
+
+> HighlineWrapper.new.ask_checkbox("What are your favorite numbers of these?", ['one', 'two','three'], {defaults: ['two', 'three']})
+What are your favorite numbers of these?
+1. one
+2. two
+3. three
+
+=> [{:value=>"two"}, {:value=>"three"}]
+
+> HighlineWrapper.new.ask_checkbox("What are your favorite numbers of these?", ['one', 'two','three'], {required: true, with_indexes: true})
+What are your favorite numbers of these?
+1. one
+2. two
+3. three
+
+This question is required.
+
+What are your favorite numbers of these?
+1. one
+2. two
+3. three
+2
+
+=> [{:value=>"two", :index=>1}]
+
+> HighlineWrapper.new.ask_checkbox("What are your favorite numbers of these?", ['one', 'two','three'], {required: true, with_indexes: false})
+What are your favorite numbers of these?
+1. one
+2. two
+3. three
+
+This question is required.
+
+What are your favorite numbers of these?
+1. one
+2. two
+3. three
+1
+
+=> [{:value=>"one"}]
+
+> HighlineWrapper.new.ask_checkbox("What are your favorite numbers of these?", ['one', 'two','three'], {defaults: []})
+What are your favorite numbers of these?
+1. one
+2. two
+3. three
+
+=> []
+
+> HighlineWrapper.new.ask_checkbox("What are your favorite numbers of these?", ['one', 'two','three'], {defaults: [], with_indexes: true})
+What are your favorite numbers of these?
+1. one
+2. two
+3. three
+
+=> []
 ```
 
-### Tests
+</details>
+
+## Tests
 
 To run the tests, run `bundle exec rspec` from the command line. GitHub Actions will also run the tests upon every commit to make sure they're up to date and that everything is working correctly. Locally, you can also run `bundle exec guard` to automatically run tests as you develop!
 

data/lib/highline_wrapper.rb

@@ -9,42 +9,93 @@ Dir[files].each do |file|
 end
 
 class HighlineWrapper
-  # Returns - string; the answer to the question
-  # prompt - string; the prompt for the question
-  def ask(prompt, secret: false)
-    client.ask(prompt, secret)
+  # Returns: the answer to the question (string)
+  #
+  # prompt: the prompt for the question (string)
+  # options: various options to pass to the questions (hash)
+  #   secret: whether the terminal should hide the typed value (boolean - defaults to false)
+  #   default: the default selection (string - defaults to '')
+  #   required: whether the question is required or not (boolean - defaults to false)
+  #
+  # Notes:
+  #  If required == true, the question will repeat until the user answers the question
+  #  If required == true, then the default value will be ignored
+  def ask(prompt, options = {})
+    defaults = {
+      secret: false,
+      default: '',
+      required: false
+    }
+    options = defaults.merge(options)
+    HighlineWrapper::OpenEndedQuestion.ask(prompt, options)
   end
 
-  # Returns - boolean; yes for true, no for false
-  # prompt - string; the prompt for the question
-  # preference - boolean; whether skipping the question should return true or false
-  def ask_yes_no(prompt, preference: true)
-    client.ask_yes_no(prompt, preference)
+  # Returns: yes for true, no for false (boolean)
+  #
+  # prompt: the prompt for the question (string)
+  # options: various options to pass to the questions (hash)
+  #   default: the default selection (boolean - defaults to true)
+  #   required: whether the question is required or not (boolean - defaults to false)
+  #
+  # Notes:
+  #  If required == true, the question will repeat until the user answers the question
+  #  If required == true, then the default value will be ignored
+  def ask_yes_no(prompt, options = {})
+    defaults = {
+      default: true,
+      required: false
+    }
+    options = defaults.merge(options)
+    HighlineWrapper::YesNoQuestion.ask(prompt, options)
   end
 
-  # Returns - string OR hash; the selection
-  #   e.g. 'c'
-  # prompt - string; the prompt for the question
-  # choices - array; an array of string options
-  #   e.g. [ 'a', 'b', 'c' ]
-  # with_index - boolean; whether to return the index of the selection
-  #   e.g. { choice: 'c', index: 2 }
-  def ask_multiple_choice(prompt, choices, with_index: false)
-    client.ask_multiple_choice(prompt, choices, with_index)
+  # Returns: the selection in a hash (hash)
+  #   e.g. { value: 'c' }
+  #   e.g. { value: 'c', index: 2 }
+  #
+  # prompt: the prompt for the question (string)
+  # choices: a list of string options (array) (e.g. [ 'a', 'b', 'c' ])
+  # options: various options to pass to the questions (hash)
+  #   with_index: whether to return the index of the selection (boolean - defaults to false)
+  #   default: the default selection if the user skips the question (string - defaults to nil)
+  #   required: whether the question is required or not (boolean - defaults to false)
+  #
+  # Notes:
+  #   If required == true, the question will repeat until the user answers the question
+  #   If required == true, then the default value will be ignored
+  #   If default == nil and required == false, and the user skips the question, the answer will be nil
+  def ask_multiple_choice(prompt, choices, options = {})
+    defaults = {
+      with_index: false,
+      default: nil,
+      required: false
+    }
+    options = defaults.merge(options)
+    HighlineWrapper::MultipleChoiceQuestion.ask(prompt, choices, options)
   end
 
-  # Returns - array; an array of selections
-  #   e.g. [ 'a', 'c' ]
-  # prompt - string; the prompt for the question
-  # choices - array; an array of string options
-  #   e.g. [ 'a', 'b', 'c' ]
-  # with_indexes - boolean; whether to return the indices of the selections
-  #   e.g. [ { choice: 'a', index: 0 }, { choice: 'c', index: 2 } ]
-  def ask_checkbox(prompt, choices, with_indexes: false)
-    client.ask_checkbox(prompt, choices, with_indexes)
-  end
-
-  private def client
-    @client ||= HighlineWrapper::Client.new
+  # Returns: the selections chosen as an array of hashes (array)
+  #   e.g. [{ value: 'a' }, { value: 'c' }]
+  #   e.g. [{ value: 'a', index: 0 }, { value: 'c', index: 2 }])
+  #
+  # prompt: the prompt for the question (string)
+  # choices: a list of string options (array) (e.g. [ 'a', 'b', 'c' ])
+  # options: various options to pass to the questions (hash)
+  #   with_indexes: whether to return the indexes of the selections (boolean - defaults to false)
+  #   defaults: the default selections if the user skips the question (array - defaults to [])
+  #   required: whether the question is required or not (boolean - defaults to false)
+  #
+  # Notes:
+  #   If required == true, the question will repeat until the user answers the question
+  #   If required == true, then the defaults value will be ignored
+  #   If defaults == [] and required == false, then the method will return an empty array
+  def ask_checkbox(prompt, choices, options = {})
+    defaults = {
+      with_indexes: false,
+      defaults: [],
+      required: false
+    }
+    options = defaults.merge(options)
+    HighlineWrapper::CheckboxQuestion.ask(prompt, choices, options)
   end
 end