command_kit 0.1.0.pre2 → 0.1.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: baf0cab5c4519bef85a5ac27597c1c67b28a77cbe86d6c34b72687a91e1ef906
-  data.tar.gz: 1b816bb979dcff48caf5c09ac7f4dcd9006871c94b9fd3bee5a7c2ce1763815a
+  metadata.gz: 5c8944ddc49470bbe03b23cdf0df4cc9e5f94010208e15b373430453556ff2ed
+  data.tar.gz: bfebe1ddb5ae5a078e5910de55f626ae69dc8716f3d5152690e9002b68878bfe
 SHA512:
-  metadata.gz: 284c9a6ff6bb1584add29558658054fc0814cfc0b1a1609b16a577154bc85e7011d9989abc75418bbd631f00a5f6c444dd104b3d938be347ad32ddf08e84ec83
-  data.tar.gz: f0df98d7654058aa5be0aa884703ef540be3a1b7e2be52cd4a975913731ee4572d30cfc1a7b5213b9a165e7a18f95f4bbd3d9eb1a217362370a6c3b9e6c7ea93
+  metadata.gz: a8f00bba78443b945ea4c41efeaf4488eb6c65867ac637b4ae368d6a53724802395f0f9d5d464241fbe9d7f22fd1657e50161df4846fcdcce174f4abf206abb7
+  data.tar.gz: 497da95cec49705d426da9dfa27aa5f7ca9e462375dba94375244e5180f9ac9f1735850022fdfd61876cb6661a5988c568eda518dac010859be69589c3780843

data/ChangeLog.md

@@ -1,13 +1,13 @@
-### 0.1.0 / 2021-05-XX
+### 0.1.0 / 2021-07-XX
 
 * Initial release:
   * {CommandKit::Arguments}
   * {CommandKit::Colors}
+  * {CommandKit::Command}
   * {CommandKit::CommandName}
   * {CommandKit::Commands}
     * {CommandKit::Commands::AutoLoad}
     * {CommandKit::Commands::AutoRequire}
-  * {CommandKit::Console}
   * {CommandKit::Description}
   * {CommandKit::Env}
     * {CommandKit::Env::Home}
@@ -16,14 +16,17 @@
   * {CommandKit::ExceptionHandler}
   * {CommandKit::Help}
     * {CommandKit::Help::Man}
+  * {CommandKit::Interactive}
   * {CommandKit::Main}
   * {CommandKit::Options}
     * {CommandKit::Options::Quiet}
     * {CommandKit::Options::Verbose}
   * {CommandKit::Pager}
   * {CommandKit::Printing}
+    * {CommandKit::Printing::Indent}
   * {CommandKit::ProgramName}
   * {CommandKit::Stdio}
+  * {CommandKit::Terminal}
   * {CommandKit::Usage}
   * {CommandKit::XDG}
 

data/README.md

@@ -7,8 +7,8 @@
 
 ## Description
 
-A Ruby toolkit for building clean, correct, and robust CLI commands as Ruby
-classes.
+A Ruby toolkit for building clean, correct, and robust CLI commands as
+plain-old Ruby classes.
 
 ## Features
 
@@ -18,13 +18,13 @@ classes.
 * Supports subcommands (explicit or lazy-loaded) and command aliases.
 * Correctly handles Ctrl^C and SIGINT interrupts (aka exit 130).
 * Correctly handles broken pipes (aka `mycmd | head`).
-* Uses [OptionParser][optparse] for option parsing.
-* Provides ANSI coloring support.
+* Correctly handles when stdout or stdin is redirected to a file.
+* Uses [OptionParser][optparse] for POSIX option parsing.
+* Supports optional ANSI coloring.
 * Supports optionally displaying a man-page instead of `--help`
   (see {CommandKit::Help::Man}).
 * Supports XDG directories (`~/.config/`, `~/.local/share/`, `~/.cache/`).
 * Easy to test (ex: `MyCmd.main(arg1, arg2, options: {foo: foo}) # => 0`)
-* Modular design (everything is a module).
 
 ### API
 
@@ -35,7 +35,6 @@ classes.
 * [CommandKit::Commands](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands)
   * [CommandKit::Commands::AutoLoad](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands/AutoLoad)
   * [CommandKit::Commands::AutoRequire](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands/AutoRequire)
-* [CommandKit::Console](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Console)
 * [CommandKit::Description](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Description)
 * [CommandKit::Env](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env)
   * [CommandKit::Env::Home](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env/Home)
@@ -44,6 +43,7 @@ classes.
 * [CommandKit::ExceptionHandler](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/ExceptionHandler)
 * [CommandKit::Help](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Help)
   * [CommandKit::Help::Man](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Help/Man)
+* [CommandKit::Interactive](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Interactive)
 * [CommandKit::Main](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Main)
 * [CommandKit::Options](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options)
   * [CommandKit::Options::Quiet](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options/Quiet)
@@ -53,6 +53,7 @@ classes.
   * [CommandKit::Printing::Indent](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Printing/Indent)
 * [CommandKit::ProgramName](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/ProgramName)
 * [CommandKit::Stdio](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Stdio)
+* [CommandKit::Terminal](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Terminal)
 * [CommandKit::Usage](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Usage)
 * [CommandKit::XDG](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/XDG)
 

data/gemspec.yml

@@ -2,7 +2,8 @@ name: command_kit
 summary: A toolkit for building Ruby CLI commands
 description:
   A Ruby toolkit for building clean, correct, and robust CLI commands as
-  Ruby classes.
+  plain-old Ruby classes.
+
 license: MIT
 authors: Postmodern
 email: postmodern.mod3@gmail.com

data/lib/command_kit/interactive.rb

@@ -0,0 +1,178 @@
+require 'command_kit/stdio'
+
+module CommandKit
+  module Interactive
+    include Stdio
+
+    #
+    # Asks the user for input.
+    #
+    # @param [String] prompt
+    #   The prompt that will be printed before reading input.
+    #
+    # @param [String, nil] default
+    #   The default value to return if no input is given.
+    #
+    # @param [Boolean] required
+    #   Requires non-empty input.
+    #
+    # @return [String]
+    #   The user input.
+    #
+    def ask(prompt, default: nil, required: false)
+      prompt = prompt.chomp
+      prompt << " [#{default}]" if default
+      prompt << ": "
+
+      stdout.print(prompt)
+
+      loop do
+        value = stdin.gets
+        value ||= '' # convert nil values (ctrl^D) to an empty String
+
+        if value.empty?
+          if required
+            next
+          else
+            return (default || value)
+          end
+        else
+          return value
+        end
+      end
+    end
+
+    #
+    # Asks the user a yes or no question.
+    #
+    # @param [String] prompt
+    #   The prompt that will be printed before reading input.
+    #
+    # @param [true, false,  nil] default
+    #
+    # @return [Boolean]
+    #   Specifies whether the user entered Y/yes.
+    #
+    # @example
+    #   ask_yes_or_no("Proceed anyways?")
+    #   # Proceed anyways? (Y/N): Y
+    #   # => :yes
+    #
+    def ask_yes_or_no(prompt, default: nil, **kwargs)
+      default = case default
+                when true  then 'Y'
+                when false then 'N'
+                when nil  then nil
+                else
+                  raise(ArgumentError,"invalid default: #{default.inspect}")
+                end
+
+      prompt = "#{prompt} (Y/N)"
+
+      loop do
+        answer = ask(prompt, **kwargs, default: default)
+
+        case answer.downcase
+        when 'y', 'yes'
+          return true
+        else
+          return false
+        end
+      end
+    end
+
+    #
+    # Asks the user to select a choice from a list of options.
+    #
+    # @param [String] prompt
+    #   The prompt that will be printed before reading input.
+    #
+    # @param [Hash{String => String}, Array<String>] choices
+    #   The choices to select from.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments for {#ask}.
+    #
+    # @option kwargs [String, nil] default
+    #   The default option to fallback to, if no input is given.
+    #
+    # @option kwargs [Boolean] required
+    #   Requires non-empty input.
+    #
+    # @return [String]
+    #   The selected choice.
+    #
+    # @example Array of choices:
+    #   ask_multiple_choice("Select a flavor", %w[Apple Orange Lemon Lime])
+    #   #   1) Apple
+    #   #   2) Orange
+    #   #   3) Lemon
+    #   #   4) Lime
+    #   #   Select a flavor: 4
+    #   #
+    #   # => "Lime"
+    #
+    # @example Hash of choices:
+    #   ask_multiple_choice("Select an option", {'A' => 'Foo',
+    #                                            'B' => 'Bar',
+    #                                            'X' => 'All of the above'})
+    #   #   A) Foo
+    #   #   B) Bar
+    #   #   X) All of the above
+    #   #   Select an option: X
+    #   #
+    #   # => "All of the above"
+    #
+    def ask_multiple_choice(prompt,choices,**kwargs)
+      choices = case choices
+                when Array
+                  Hash[choices.each_with_index.map { |value,i|
+                    [(i+1).to_s, value]
+                  }]
+                when Hash
+                  choices
+                else
+                  raise(TypeError,"unsupported choices class #{choices.class}: #{choices.inspect}")
+                end
+
+      prompt = "#{prompt} (#{choices.keys.join(', ')})"
+
+      loop do
+        # print the choices
+        choices.each do |choice,value|
+          stdout.puts "  #{choice}) #{value}"
+        end
+        stdout.puts
+
+        # read the choice
+        choice = ask(prompt,**kwargs)
+
+        if choices.has_key?(choice)
+          # if a valid choice is given, return the value
+          return choices[choice]
+        else
+          stderr.puts "Invalid selection: #{choice}"
+        end
+      end
+    end
+
+    #
+    # Asks the user for secret input.
+    #
+    # @example
+    #   ask_secret("Password")
+    #   # Password: 
+    #   # => "s3cr3t"
+    #
+    def ask_secret(prompt, required: true)
+      if stdin.respond_to?(:noecho)
+        stdin.noecho do
+          ask(prompt, required: required)
+        end
+      else
+        ask(prompt, required: required)
+      end
+    end
+
+  end
+end

data/lib/command_kit/pager.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require 'command_kit/stdio'
-require 'command_kit/console'
 require 'command_kit/env'
 require 'command_kit/env/path'
+require 'command_kit/stdio'
+require 'command_kit/terminal'
 
 module CommandKit
   #
@@ -35,10 +35,10 @@ module CommandKit
   # * [tty-pager](https://github.com/piotrmurach/tty-pager#readme)
   #
   module Pager
-    include Stdio
-    include Console
     include Env
     include Env::Path
+    include Stdio
+    include Terminal
 
     # Common pager commands.
     PAGERS = ['less -r', 'more -r']
@@ -76,7 +76,7 @@ module CommandKit
     #
     def pager
       if !stdout.tty? || @pager.nil?
-        # fallback to stdout if the process does not have a console or we could
+        # fallback to stdout if the process does not have a terminal or we could
         # not find a suitable pager command.
         yield stdout
         return
@@ -99,7 +99,7 @@ module CommandKit
     end
 
     #
-    # Pages the data if it's longer the console's height, otherwise prints the
+    # Pages the data if it's longer the terminal's height, otherwise prints the
     # data to {Stdio#stdout stdout}.
     #
     # @param [Array<String>, #to_s] data
@@ -111,7 +111,7 @@ module CommandKit
                    else             data.to_s.each_line.count
                    end
 
-      if line_count > console_height
+      if line_count > terminal_height
         pager { |io| io.puts(data) }
       else
         stdout.puts(data)

data/lib/command_kit/terminal.rb

@@ -0,0 +1,142 @@
+require 'command_kit/stdio'
+require 'command_kit/env'
+
+begin
+  require 'io/console'
+rescue LoadError
+end
+
+module CommandKit
+  #
+  # Provides direct access to the terminal.
+  #
+  # ## Environment Variables
+  #
+  # * `LINES` - The explicit number of lines or rows the console should have.
+  # * `COLUMNS` - The explicit number of columns the console should have.
+  #
+  # @see https://rubydoc.info/gems/io-console/IO
+  #
+  module Terminal
+    include Stdio
+    include Env
+
+    # The default terminal height to fallback to.
+    DEFAULT_TERMINAL_HEIGHT = 25
+
+    # The default terminal width to fallback to.
+    DEFAULT_TERMINAL_WIDTH = 80
+
+    #
+    # Initializes any terminal settings.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @note
+    #   If the `$LINES` env variable is set, and is non-zero, it will be
+    #   returned by {#terminal_height}.
+    #
+    # @note
+    #   If the `$COLUMNS` env variable is set, and is non-zero, it will be
+    #   returned by {#terminal_width}.
+    #
+    def initialize(**kwargs)
+      super(**kwargs)
+
+      @terminal_height = if (lines = env['LINES'])
+                           lines.to_i
+                         else
+                           DEFAULT_TERMINAL_HEIGHT
+                         end
+
+      @terminal_width  = if (columns = env['COLUMNS'])
+                           columns.to_i
+                         else
+                           DEFAULT_TERMINAL_WIDTH
+                         end
+    end
+
+    #
+    # Determines if program is running in a terminal.
+    #
+    # @return [Boolean]
+    #   Specifies whether {Stdio#stdout stdout} is connected to a terminal.
+    #
+    def terminal?
+      IO.respond_to?(:console) && stdout.tty?
+    end
+
+    #
+    # Returns the terminal object, if {Stdio#stdout stdout} is connected to a
+    # terminal.
+    #
+    # @return [IO, nil]
+    #   The IO objects or `nil` if {Stdio#stdout stdout} is not connected to a
+    #   terminal.
+    #
+    # @example
+    #   terminal
+    #   # => #<File:/dev/tty>
+    #
+    # @see https://rubydoc.info/gems/io-console/IO
+    #
+    def terminal
+      IO.console if terminal?
+    end
+
+    #
+    # Returns the terminal's height in number of lines.
+    #
+    # @return [Integer]
+    #   The terminal's height in number of lines.
+    #
+    # @example
+    #   terminal_height
+    #   # => 22
+    #
+    def terminal_height
+      if (terminal = self.terminal)
+        terminal.winsize[0]
+      else
+        @terminal_height
+      end
+    end
+
+    #
+    # Returns the terminal's width in number of lines.
+    #
+    # @return [Integer]
+    #   The terminal's width in number of columns.
+    #
+    # @example
+    #   terminal_width
+    #   # => 91
+    #
+    def terminal_width
+      if (terminal = self.terminal)
+        terminal.winsize[1]
+      else
+        @terminal_width
+      end
+    end
+
+    #
+    # The terminal height (lines) and width (columns).
+    #
+    # @return [(Integer, Integer)]
+    #   Returns the height and width of the terminal.
+    #
+    # @example
+    #   terminal_size
+    #   # => [23, 91]
+    #
+    def terminal_size
+      if (terminal = self.terminal)
+        terminal.winsize
+      else
+        [@terminal_height, @terminal_width]
+      end
+    end
+  end
+end

data/lib/command_kit/version.rb

@@ -1,4 +1,4 @@
 module CommandKit
   # command_kit version
-  VERSION = "0.1.0.pre2"
+  VERSION = "0.1.0.rc1"
 end

data/spec/interactive_spec.rb

@@ -0,0 +1,415 @@
+require 'spec_helper'
+require 'command_kit/interactive'
+
+describe CommandKit::Interactive do
+  module TestInteractive
+    class TestCommand
+      include CommandKit::Interactive
+    end
+  end
+
+  let(:command_class) { TestInteractive::TestCommand }
+
+  describe "#included" do
+    subject { command_class }
+
+    it { expect(subject).to include(CommandKit::Stdio) }
+  end
+
+  let(:stdout) { StringIO.new }
+  let(:stdin)  { StringIO.new }
+  let(:stderr) { StringIO.new }
+
+  subject do
+    command_class.new(stdout: stdout, stdin: stdin, stderr: stderr)
+  end
+
+  let(:prompt) { 'Prompt' }
+
+  describe "#ask" do
+    let(:input)  { 'foo' }
+
+    it "must print a prompt, read input, and return the input" do
+      expect(stdout).to receive(:print).with("#{prompt}: ")
+      expect(stdin).to receive(:gets).and_return(input)
+
+      expect(subject.ask(prompt)).to eq(input)
+    end
+
+    it "must accept empty user input by default" do
+      expect(stdin).to receive(:gets).and_return("")
+
+      expect(subject.ask(prompt)).to eq("")
+    end
+
+    context "when Ctrl^C is entered" do
+      it "must return \"\"" do
+        expect(stdin).to receive(:gets).and_return(nil) # simulate Ctrl^C
+
+        expect(subject.ask(prompt)).to eq("")
+      end
+    end
+
+    context "when default: is given" do
+      let(:default) { 'bar' }
+
+      it "must include the default: value in the prompt" do
+        expect(stdout).to receive(:print).with("#{prompt} [#{default}]: ")
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask(prompt, default: default)).to eq(input)
+      end
+
+      context "and non-empty user input is given" do
+        it "must return the non-empty user input" do
+          expect(stdin).to receive(:gets).and_return(input)
+
+          expect(subject.ask(prompt, default: default)).to eq(input)
+        end
+      end
+
+      context "and empty user input is given" do
+        it "must return the default value" do
+          expect(stdin).to receive(:gets).and_return("")
+
+          expect(subject.ask(prompt, default: default)).to eq(default)
+        end
+      end
+    end
+
+    context "when required: is given" do
+      context "and empty user input is given" do
+        it "must ask for input again, until non-empty input is given" do
+          expect(stdin).to receive(:gets).and_return("")
+          expect(stdin).to receive(:gets).and_return("")
+          expect(stdin).to receive(:gets).and_return(input)
+
+          expect(subject.ask(prompt, required: true)).to eq(input)
+        end
+      end
+
+      context "and non-empty user input is given" do
+        it "must return the non-empty user input" do
+          expect(stdin).to receive(:gets).and_return(input)
+
+          expect(subject.ask(prompt, required: true)).to eq(input)
+        end
+      end
+    end
+  end
+
+  describe "#ask_yes_or_no" do
+    let(:input) { 'Y' }
+
+    it "must print a prompt indicating Y/N, and then accept input" do
+      expect(stdout).to receive(:print).with("#{prompt} (Y/N): ")
+      expect(stdin).to receive(:gets).and_return(input)
+
+      subject.ask_yes_or_no(prompt)
+    end
+
+    context "when 'Y' is entered" do
+      let(:input) { 'Y' }
+
+      it "must return true" do
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_yes_or_no(prompt)).to eq(true)
+      end
+    end
+
+    context "when 'y' is entered" do
+      let(:input) { 'y' }
+
+      it "must return true" do
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_yes_or_no(prompt)).to eq(true)
+      end
+    end
+
+    context "when 'YES' is entered" do
+      let(:input) { 'YES' }
+
+      it "must return true" do
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_yes_or_no(prompt)).to eq(true)
+      end
+    end
+
+    context "when 'Yes' is entered" do
+      let(:input) { 'Yes' }
+
+      it "must return true" do
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_yes_or_no(prompt)).to eq(true)
+      end
+    end
+
+    context "when 'yes' is entered" do
+      let(:input) { 'yes' }
+
+      it "must return true" do
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_yes_or_no(prompt)).to eq(true)
+      end
+    end
+
+    context "when 'N' is entered" do
+      let(:input) { 'N' }
+
+      it "must return false" do
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_yes_or_no(prompt)).to eq(false)
+      end
+    end
+
+    context "when 'n' is entered" do
+      let(:input) { 'n' }
+
+      it "must return false" do
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_yes_or_no(prompt)).to eq(false)
+      end
+    end
+
+    context "when 'NO' is entered" do
+      let(:input) { 'NO' }
+
+      it "must return false" do
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_yes_or_no(prompt)).to eq(false)
+      end
+    end
+
+    context "when 'No' is entered" do
+      let(:input) { 'No' }
+
+      it "must return false" do
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_yes_or_no(prompt)).to eq(false)
+      end
+    end
+
+    context "when 'no' is entered" do
+      let(:input) { 'no' }
+
+      it "must return false" do
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_yes_or_no(prompt)).to eq(false)
+      end
+    end
+
+    context "when input besides y/n/yes/no is entered" do
+      let(:input) { 'jflksjfls' }
+
+      it "must return false" do
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_yes_or_no(prompt)).to eq(false)
+      end
+    end
+
+    context "when defualt: is given" do
+      context "and is true" do
+        let(:default) { true }
+
+        it "must include [Y] in the prompt" do
+          expect(stdout).to receive(:print).with("#{prompt} (Y/N) [Y]: ")
+          expect(stdin).to receive(:gets).and_return(input)
+
+          subject.ask_yes_or_no(prompt, default: default)
+        end
+
+        context "and empty user-input is given" do
+          let(:input) { "" }
+
+          it "must return true" do
+            expect(stdout).to receive(:print).with("#{prompt} (Y/N) [Y]: ")
+            expect(stdin).to receive(:gets).and_return(input)
+
+            expect(subject.ask_yes_or_no(prompt, default: default)).to eq(default)
+          end
+        end
+      end
+
+      context "and is false" do
+        let(:default) { false }
+
+        it "must include [N] in the prompt" do
+          expect(stdout).to receive(:print).with("#{prompt} (Y/N) [N]: ")
+          expect(stdin).to receive(:gets).and_return(input)
+
+          subject.ask_yes_or_no(prompt, default: default)
+        end
+
+        context "and empty user-input is given" do
+          let(:input) { "" }
+
+          it "must return false" do
+            expect(stdout).to receive(:print).with("#{prompt} (Y/N) [N]: ")
+            expect(stdin).to receive(:gets).and_return(input)
+
+            expect(subject.ask_yes_or_no(prompt, default: default)).to eq(default)
+          end
+        end
+      end
+    end
+  end
+
+  describe "#ask_multiple_choice" do
+    context "when given an Array" do
+      let(:choices) do
+        [
+          "foo",
+          "bar",
+          "baz"
+        ]
+      end
+
+      let(:input) { "2" }
+
+      it "must print the numbered choices, a prompt with the choices, read input, and return the choice" do
+        expect(stdout).to receive(:puts).with("  1) #{choices[0]}")
+        expect(stdout).to receive(:puts).with("  2) #{choices[1]}")
+        expect(stdout).to receive(:puts).with("  3) #{choices[2]}")
+        expect(stdout).to receive(:puts).with(no_args)
+        expect(stdout).to receive(:print).with("#{prompt} (1, 2, 3): ")
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_multiple_choice(prompt,choices)).to eq(choices[input.to_i - 1])
+      end
+
+      context "when empty user-input is given" do
+        it "must ask for input again, until non-empty input is given" do
+          expect(stdin).to receive(:gets).and_return("")
+          expect(stdin).to receive(:gets).and_return("")
+          expect(stdin).to receive(:gets).and_return(input)
+
+          expect(subject.ask_multiple_choice(prompt,choices)).to eq(choices[input.to_i - 1])
+        end
+      end
+
+      context "and default: is given" do
+        let(:default) { '3' }
+
+        it "must include the default: choice in the prompt" do
+          expect(stdout).to receive(:print).with("#{prompt} (1, 2, 3) [#{default}]: ")
+          expect(stdin).to receive(:gets).and_return(input)
+
+          subject.ask_multiple_choice(prompt,choices, default: default)
+        end
+
+        context "and empty user-input is given" do
+          it "must return the value for the default choice" do
+            expect(stdin).to receive(:gets).and_return("")
+
+            expect(subject.ask_multiple_choice(prompt,choices, default: default)).to eq(choices[default.to_i - 1])
+          end
+        end
+      end
+    end
+
+    context "when given a Hash" do
+      let(:choices) do
+        {
+          "A" => "foo",
+          "B" => "bar",
+          "C" => "baz"
+        }
+      end
+
+      let(:input) { "B" }
+
+      it "must print the labeled choices, a prompt with the choices, read input, and return the choice" do
+        expect(stdout).to receive(:puts).with("  #{choices.keys[0]}) #{choices.values[0]}")
+        expect(stdout).to receive(:puts).with("  #{choices.keys[1]}) #{choices.values[1]}")
+        expect(stdout).to receive(:puts).with("  #{choices.keys[2]}) #{choices.values[2]}")
+        expect(stdout).to receive(:puts).with(no_args)
+        expect(stdout).to receive(:print).with("#{prompt} (#{choices.keys[0]}, #{choices.keys[1]}, #{choices.keys[2]}): ")
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_multiple_choice(prompt,choices)).to eq(choices[input])
+      end
+
+      context "when empty user-input is given" do
+        it "must ask for input again, until non-empty input is given" do
+          expect(stdin).to receive(:gets).and_return("")
+          expect(stdin).to receive(:gets).and_return("")
+          expect(stdin).to receive(:gets).and_return(input)
+
+          expect(subject.ask_multiple_choice(prompt,choices)).to eq(choices[input])
+        end
+      end
+
+      context "and default: is given" do
+        let(:default) { 'C' }
+
+        it "must include the default: choice in the prompt" do
+          expect(stdout).to receive(:print).with("#{prompt} (#{choices.keys[0]}, #{choices.keys[1]}, #{choices.keys[2]}) [#{default}]: ")
+          expect(stdin).to receive(:gets).and_return(input)
+
+          subject.ask_multiple_choice(prompt,choices, default: default)
+        end
+
+        context "and empty user-input is given" do
+          it "must return the value for the default choice" do
+            expect(stdin).to receive(:gets).and_return("")
+
+            expect(subject.ask_multiple_choice(prompt,choices, default: default)).to eq(choices[default])
+          end
+        end
+      end
+    end
+  end
+
+  describe "#ask_secret" do
+    let(:input) { 's3cr3t' }
+
+    context "when stdin supports to #noecho" do
+      it "must call #noecho, read input, then return the input" do
+        allow(stdin).to receive(:noecho).and_yield
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_secret(prompt)).to eq(input)
+      end
+    end
+
+    context "when stdin does not support #noecho" do
+      it "must fallback to reading input" do
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_secret(prompt)).to eq(input)
+      end
+    end
+
+    context "when empty user-input is given" do
+      it "must ask for input again, until non-empty input is given" do
+        expect(stdin).to receive(:gets).and_return("")
+        expect(stdin).to receive(:gets).and_return("")
+        expect(stdin).to receive(:gets).and_return("")
+        expect(stdin).to receive(:gets).and_return(input)
+
+        expect(subject.ask_secret(prompt)).to eq(input)
+      end
+    end
+
+    context "when required: is false" do
+      context "and empty user-input is given" do
+        it "must return the empty user-input" do
+          expect(stdin).to receive(:gets).and_return("")
+
+          expect(subject.ask_secret(prompt, required: false)).to eq("")
+        end
+      end
+    end
+  end
+end

data/spec/pager_spec.rb

@@ -95,10 +95,10 @@ describe Pager do
   end
 
   describe "#print_or_page" do
-    let(:console_height) { 10 }
+    let(:terminal_height) { 10 }
 
     before do
-      expect(subject).to receive(:console_height).and_return(console_height)
+      expect(subject).to receive(:terminal_height).and_return(terminal_height)
     end
 
     context "when given a String" do
@@ -113,7 +113,7 @@ describe Pager do
       end
 
       context "and the number of lines is greater than the console's height" do
-        let(:string) { "foo#{$/}bar#{$/}" * console_height }
+        let(:string) { "foo#{$/}bar#{$/}" * terminal_height }
 
         it "must spawn a pager and puts the String to the pager" do
           pager = double('pager')
@@ -137,7 +137,7 @@ describe Pager do
       end
 
       context "and the number of lines is greater than the console's height" do
-        let(:array) { ['foo', 'bar'] * console_height }
+        let(:array) { ['foo', 'bar'] * terminal_height }
 
         it "must spawn a pager and puts the Array of Strings to the pager" do
           pager = double('pager')

data/spec/{console_spec.rb → terminal_spec.rb}

@@ -1,26 +1,26 @@
 require 'spec_helper'
-require 'command_kit/console'
+require 'command_kit/terminal'
 
 require 'stringio'
 
-describe Console do
-  module TestConsole
+describe Terminal do
+  module TestTerminal
     class TestCommand
-      include CommandKit::Console
+      include CommandKit::Terminal
     end
   end
 
-  let(:command_class) { TestConsole::TestCommand }
+  let(:command_class) { TestTerminal::TestCommand }
   subject { command_class.new }
 
-  describe "#console?" do
+  describe "#terminal?" do
     context "when stdout is connected to a TTY" do
       subject { command_class.new(stdout: STDOUT) }
 
       it do
         skip "STDOUT is not a TTY" unless STDOUT.tty?
 
-        expect(subject.console?).to be(true)
+        expect(subject.terminal?).to be(true)
       end
     end
 
@@ -28,7 +28,7 @@ describe Console do
       subject { command_class.new(stdout: StringIO.new) }
 
       it do
-        expect(subject.console?).to be(false)
+        expect(subject.terminal?).to be(false)
       end
     end
 
@@ -38,19 +38,19 @@ describe Console do
       end
 
       it do
-        expect(subject.console?).to be(false)
+        expect(subject.terminal?).to be(false)
       end
     end
   end
 
-  describe "#console" do
+  describe "#terminal" do
     context "when stdout is connected to a TTY" do
       subject { command_class.new(stdout: STDOUT) }
 
       it do
         skip "STDOUT is not a TTY" unless STDOUT.tty?
 
-        expect(subject.console).to eq(IO.console)
+        expect(subject.terminal).to eq(IO.console)
       end
     end
 
@@ -58,7 +58,7 @@ describe Console do
       subject { command_class.new(stdout: StringIO.new) }
 
       it do
-        expect(subject.console).to eq(nil)
+        expect(subject.terminal).to eq(nil)
       end
     end
 
@@ -68,27 +68,27 @@ describe Console do
       end
 
       it do
-        expect(subject.console).to be(nil)
+        expect(subject.terminal).to be(nil)
       end
     end
   end
 
-  describe "#console_height" do
+  describe "#terminal_height" do
     context "when stdout is connected to a TTY" do
       subject { command_class.new(stdout: STDOUT) }
 
       it do
         skip "STDOUT is not a TTY" unless STDOUT.tty?
 
-        expect(subject.console_height).to eq(STDOUT.winsize[0])
+        expect(subject.terminal_height).to eq(STDOUT.winsize[0])
       end
     end
 
     context "when stdout is not connected to a TTY" do
       subject { command_class.new(stdout: StringIO.new) }
 
-      it "must fallback to DEFAULT_HEIGHT" do
-        expect(subject.console_height).to eq(described_class::DEFAULT_HEIGHT)
+      it "must fallback to DEFAULT_TERMINAL_HEIGHT" do
+        expect(subject.terminal_height).to eq(described_class::DEFAULT_TERMINAL_HEIGHT)
       end
 
       context "but the LINES env variable was set" do
@@ -98,28 +98,28 @@ describe Console do
         subject { command_class.new(stdout: StringIO.new, env: env) }
 
         it "must fallback to the LINES environment variable" do
-          expect(subject.console_height).to eq(lines)
+          expect(subject.terminal_height).to eq(lines)
         end
       end
     end
   end
 
-  describe "#console_width" do
+  describe "#terminal_width" do
     context "when stdout is connected to a TTY" do
       subject { command_class.new(stdout: STDOUT) }
 
       it do
         skip "STDOUT is not a TTY" unless STDOUT.tty?
 
-        expect(subject.console_width).to eq(STDOUT.winsize[1])
+        expect(subject.terminal_width).to eq(STDOUT.winsize[1])
       end
     end
 
     context "when stdout is not connected to a TTY" do
       subject { command_class.new(stdout: StringIO.new) }
 
-      it "must fallback to DEFAULT_WIDTH" do
-        expect(subject.console_width).to eq(described_class::DEFAULT_WIDTH)
+      it "must fallback to DEFAULT_TERMINAL_WIDTH" do
+        expect(subject.terminal_width).to eq(described_class::DEFAULT_TERMINAL_WIDTH)
       end
 
       context "but the COLUMNS env variable was set" do
@@ -129,29 +129,29 @@ describe Console do
         subject { command_class.new(stdout: StringIO.new, env: env) }
 
         it "must fallback to the COLUMNS environment variable" do
-          expect(subject.console_width).to eq(columns)
+          expect(subject.terminal_width).to eq(columns)
         end
       end
     end
   end
 
-  describe "#console_size" do
+  describe "#terminal_size" do
     context "when stdout is connected to a TTY" do
       subject { command_class.new(stdout: STDOUT) }
 
       it do
         skip "STDOUT is not a TTY" unless STDOUT.tty?
 
-        expect(subject.console_size).to eq(STDOUT.winsize)
+        expect(subject.terminal_size).to eq(STDOUT.winsize)
       end
     end
 
     context "when stdout is not connected to a TTY" do
       subject { command_class.new(stdout: StringIO.new) }
 
-      it "must fallback to [DEFAULT_HEIGHT, DEFAULT_WIDTH]" do
-        expect(subject.console_size).to eq(
-          [described_class::DEFAULT_HEIGHT, described_class::DEFAULT_WIDTH]
+      it "must fallback to [DEFAULT_TERMINAL_HEIGHT, DEFAULT_TERMINAL_WIDTH]" do
+        expect(subject.terminal_size).to eq(
+          [described_class::DEFAULT_TERMINAL_HEIGHT, described_class::DEFAULT_TERMINAL_WIDTH]
         )
       end
 
@@ -161,9 +161,9 @@ describe Console do
 
         subject { command_class.new(stdout: StringIO.new, env: env) }
 
-        it "must fallback to the [$LINES, DEFAULT_WIDTH]" do
-          expect(subject.console_size).to eq(
-            [lines, described_class::DEFAULT_WIDTH]
+        it "must fallback to the [$LINES, DEFAULT_TERMINAL_WIDTH]" do
+          expect(subject.terminal_size).to eq(
+            [lines, described_class::DEFAULT_TERMINAL_WIDTH]
           )
         end
       end
@@ -174,9 +174,9 @@ describe Console do
 
         subject { command_class.new(stdout: StringIO.new, env: env) }
 
-        it "must fallback to the [DEFAULT_HEIGHT, COLUMNS]" do
-          expect(subject.console_size).to eq(
-            [described_class::DEFAULT_HEIGHT, columns]
+        it "must fallback to the [DEFAULT_TERMINAL_HEIGHT, COLUMNS]" do
+          expect(subject.terminal_size).to eq(
+            [described_class::DEFAULT_TERMINAL_HEIGHT, columns]
           )
         end
       end
@@ -191,7 +191,7 @@ describe Console do
         subject { command_class.new(stdout: StringIO.new, env: env) }
 
         it "must fallback to the [LINES, COLUMNS]" do
-          expect(subject.console_size).to eq(
+          expect(subject.terminal_size).to eq(
             [lines, columns]
           )
         end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_kit
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre2
+  version: 0.1.0.rc1
 platform: ruby
 authors:
 - Postmodern
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-28 00:00:00.000000000 Z
+date: 2021-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -25,7 +25,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.0'
 description: A Ruby toolkit for building clean, correct, and robust CLI commands as
-  Ruby classes.
+  plain-old Ruby classes.
 email: postmodern.mod3@gmail.com
 executables: []
 extensions: []
@@ -64,7 +64,6 @@ files:
 - lib/command_kit/commands/help.rb
 - lib/command_kit/commands/parent_command.rb
 - lib/command_kit/commands/subcommand.rb
-- lib/command_kit/console.rb
 - lib/command_kit/description.rb
 - lib/command_kit/env.rb
 - lib/command_kit/env/home.rb
@@ -74,6 +73,7 @@ files:
 - lib/command_kit/help.rb
 - lib/command_kit/help/man.rb
 - lib/command_kit/inflector.rb
+- lib/command_kit/interactive.rb
 - lib/command_kit/main.rb
 - lib/command_kit/options.rb
 - lib/command_kit/options/option.rb
@@ -88,6 +88,7 @@ files:
 - lib/command_kit/printing/indent.rb
 - lib/command_kit/program_name.rb
 - lib/command_kit/stdio.rb
+- lib/command_kit/terminal.rb
 - lib/command_kit/usage.rb
 - lib/command_kit/version.rb
 - lib/command_kit/xdg.rb
@@ -108,7 +109,6 @@ files:
 - spec/commands/parent_command_spec.rb
 - spec/commands/subcommand_spec.rb
 - spec/commands_spec.rb
-- spec/console_spec.rb
 - spec/description_spec.rb
 - spec/env/home_spec.rb
 - spec/env/path_spec.rb
@@ -118,6 +118,7 @@ files:
 - spec/help/man_spec.rb
 - spec/help_spec.rb
 - spec/inflector_spec.rb
+- spec/interactive_spec.rb
 - spec/main_spec.rb
 - spec/options/option_spec.rb
 - spec/options/option_value_spec.rb
@@ -130,6 +131,7 @@ files:
 - spec/program_name_spec.rb
 - spec/spec_helper.rb
 - spec/stdio_spec.rb
+- spec/terminal_spec.rb
 - spec/usage_spec.rb
 - spec/xdg_spec.rb
 homepage: https://github.com/postmodern/command_kit#readme

data/lib/command_kit/console.rb

@@ -1,141 +0,0 @@
-require 'command_kit/stdio'
-require 'command_kit/env'
-
-begin
-  require 'io/console'
-rescue LoadError
-end
-
-module CommandKit
-  #
-  # Provides access to [IO.console] and [IO.console_size].
-  #
-  # ## Environment Variables
-  #
-  # * `LINES` - The explicit number of lines or rows the console should have.
-  # * `COLUMNS` - The explicit number of columns the console should have.
-  #
-  # [IO.console]: https://rubydoc.info/gems/io-console/IO#console-class_method
-  # [IO#winsize]: https://rubydoc.info/gems/io-console/IO#winsize-instance_method
-  #
-  module Console
-    include Stdio
-    include Env
-
-    # The default console height to fallback to.
-    DEFAULT_HEIGHT = 25
-
-    # The default console width to fallback to.
-    DEFAULT_WIDTH = 80
-
-    #
-    # Initializes any console settings.
-    #
-    # @param [Hash{Symbol => Object}] kwargs
-    #   Additional keyword arguments.
-    #
-    # @note
-    #   If the `$LINES` env variable is set, and is non-zero, it will be
-    #   returned by {#console_height}.
-    #
-    # @note
-    #   If the `$COLUMNS` env variable is set, and is non-zero, it will be
-    #   returned by {#console_width}.
-    #
-    def initialize(**kwargs)
-      super(**kwargs)
-
-      @default_console_height = if (lines = env['LINES'])
-                                  lines.to_i
-                                else
-                                  DEFAULT_HEIGHT
-                                end
-
-      @default_console_width  = if (columns = env['COLUMNS'])
-                                  columns.to_i
-                                else
-                                  DEFAULT_WIDTH
-                                end
-    end
-
-    #
-    # Determines if there is a console present.
-    #
-    # @return [Boolean]
-    #   Specifies whether {Stdio#stdout stdout} is connected to a console.
-    #
-    def console?
-      IO.respond_to?(:console) && stdout.tty?
-    end
-
-    #
-    # Returns the console object, if {Stdio#stdout stdout} is connected to a
-    # console.
-    #
-    # @return [IO, nil]
-    #   The IO objects or `nil` if {Stdio#stdout stdout} is not connected to a
-    #   console.
-    #
-    # @example
-    #   console
-    #   # => #<File:/dev/tty>
-    #
-    def console
-      IO.console if console?
-    end
-
-    #
-    # Returns the console's height in number of lines.
-    #
-    # @return [Integer]
-    #   The console's height in number of lines.
-    #
-    # @example
-    #   console_height
-    #   # => 22
-    #
-    def console_height
-      if (console = self.console)
-        console.winsize[0]
-      else
-        @default_console_height
-      end
-    end
-
-    #
-    # Returns the console's width in number of lines.
-    #
-    # @return [Integer]
-    #   The console's width in number of columns.
-    #
-    # @example
-    #   console_width
-    #   # => 91
-    #
-    def console_width
-      if (console = self.console)
-        console.winsize[1]
-      else
-        @default_console_width
-      end
-    end
-
-    #
-    # The console height (lines) and width (columns).
-    #
-    # @return [(Integer, Integer)]
-    #   Returns the height and width of the console.
-    #
-    # @example
-    #   console_size
-    #   # => [23, 91]
-    #
-    def console_size
-      if (console = self.console)
-        console.winsize
-      else
-        [@default_console_height, @default_console_width]
-      end
-    end
-  end
-end