command_kit 0.1.0.pre1 → 0.2.0

data/lib/command_kit/env/path.rb

@@ -17,6 +17,8 @@ module CommandKit
       # The home directory.
       #
       # @return [String]
+      #
+      # @api semipublic
       attr_reader :path_dirs
 
       #
@@ -25,6 +27,8 @@ module CommandKit
       # @param [Hash{Symbol => Object}] kwargs
       #   Additional keyword arguments.
       #
+      # @api public
+      #
       def initialize(**kwargs)
         super(**kwargs)
 
@@ -41,6 +45,8 @@ module CommandKit
       #   The absolute path to the executable file, or `nil` if the command
       #   could not be found in any of the {#path_dirs}.
       #
+      # @api public
+      #
       def find_command(name)
         name = name.to_s
 
@@ -63,6 +69,15 @@ module CommandKit
       #   Specifies whether a command with the given name exists in one of the
       #   {#path_dirs}.
       #
+      # @example
+      #   if command_installed?("docker")
+      #     # ...
+      #   else
+      #     abort "Docker is not installed. Aborting"
+      #   end
+      #
+      # @api public
+      #
       def command_installed?(name)
         !find_command(name).nil?
       end

data/lib/command_kit/env.rb

@@ -23,6 +23,8 @@ module CommandKit
     # The environment variables hash.
     #
     # @return [Hash{String => String}]
+    #
+    # @api public
     attr_reader :env
 
     #
@@ -34,6 +36,8 @@ module CommandKit
     # @param [Hash{Symbol => Object}] kwargs
     #   Additional keyword arguments.
     #
+    # @api public
+    #
     def initialize(env: ENV, **kwargs)
       @env = env
 

data/lib/command_kit/examples.rb

@@ -17,6 +17,9 @@ module CommandKit
     include Help
     include CommandName
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -57,11 +60,15 @@ module CommandKit
       #     "-o output.txt path/to/file"
       #   ]
       #   
+      # @api public
+      #
       def examples(new_examples=nil)
         if new_examples
           @examples = Array(new_examples)
         else
-          @examples || (superclass.examples if superclass.kind_of?(ClassMethods))
+          @examples || if superclass.kind_of?(ClassMethods)
+                         superclass.examples
+                       end
         end
       end
     end
@@ -69,6 +76,8 @@ module CommandKit
     #
     # @see ClassMethods#examples
     #
+    # @api semipublic
+    #
     def examples
       self.class.examples
     end
@@ -76,6 +85,8 @@ module CommandKit
     #
     # Prints the command class'es example commands.
     #
+    # @api semipublic
+    #
     def help_examples
       if (examples = self.examples)
         puts
@@ -90,8 +101,10 @@ module CommandKit
     # Calls the superclass'es `#help` method, if it's defined, then calls
     # {#help_examples}.
     #
+    # @api public
+    #
     def help
-      super if defined?(super)
+      super
 
       help_examples
     end

data/lib/command_kit/exception_handler.rb

@@ -33,6 +33,8 @@ module CommandKit
     # @return [Integer]
     #   The exit status of the command.
     #
+    # @api public
+    #
     def main(argv=[])
       super(argv)
     rescue Interrupt, Errno::EPIPE => error
@@ -47,6 +49,8 @@ module CommandKit
     # @param [Exception] error
     #   The raised exception.
     #
+    # @api semipublic
+    #
     def on_exception(error)
       print_exception(error)
       exit(1)

data/lib/command_kit/help/man.rb

@@ -1,16 +1,34 @@
 # frozen_string_literal: true
 
+require 'command_kit/command_name'
+require 'command_kit/help'
+require 'command_kit/stdio'
+require 'command_kit/man'
+
 module CommandKit
   module Help
     #
     # Allows displaying a man-page instead of the usual `--help` output.
     #
-    # ## Environment Variables
+    # ## Examples
+    #
+    #     class Foo < CommandKit::Command
+    #
+    #       include CommandKit::Help::Man
     #
-    # * `TERM` - Specifies the type of terminal. When set to `DUMB`, it will
-    #   disable man-page help output.
+    #       man_dir "#{__dir__}/../../man"
+    #
+    #     end
     #
     module Man
+      include CommandName
+      include Help
+      include Stdio
+      include CommandKit::Man
+
+      #
+      # @api private
+      #
       module ModuleMethods
         #
         # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -33,7 +51,7 @@ module CommandKit
       extend ModuleMethods
 
       #
-      # Defines class-level methods.
+      # Class-level methods.
       #
       module ClassMethods
         #
@@ -46,74 +64,83 @@ module CommandKit
         #   The class'es or superclass'es man-page directory.
         #
         # @example
-        #   man_dir File.expand_path('../../../man',__FILE__)
+        #   man_dir "#{__dir__}/../../man"
+        #
+        # @api public
         #
         def man_dir(new_man_dir=nil)
           if new_man_dir
-            @man_dir = File.expand_path(new_man_dir)
+            @man_dir = new_man_dir
           else
-            @man_dir || (superclass.man_dir if superclass.kind_of?(ClassMethods))
+            @man_dir || if superclass.kind_of?(ClassMethods)
+                          superclass.man_dir
+                        end
           end
         end
-      end
 
-      #
-      # Determines if displaying man pages is supported.
-      #
-      # @return [Boolean]
-      #   Indicates whether the `TERM` environment variable is not `dumb`
-      #   and `$stdout` is a TTY.
-      #
-      def self.supported?
-        ENV['TERM'] != 'dumb' && $stdout.tty?
-      end
-
-      #
-      # Returns the man-page file name for the given command name.
-      #
-      # @param [String] command
-      #   The given command name.
-      #
-      # @return [String]
-      #   The man-page file name.
-      #
-      def man_page(command=command_name)
-        "#{command}.1"
+        #
+        # Gets or sets the class'es man-page file name.
+        #
+        # @param [String, nil] new_man_page
+        #   If a String is given, the class'es man-page file name will be set.
+        #
+        # @return [String]
+        #   The class'es or superclass'es man-page file name.
+        #
+        # @api public
+        #
+        def man_page(new_man_page=nil)
+          if new_man_page
+            @man_page = new_man_page
+          else
+            @man_page || "#{command_name}.1"
+          end
+        end
       end
 
       #
-      # Displays the given man page.
+      # Provides help information by showing one of the man pages within
+      # {ClassMethods#man_dir .man_dir}.
       #
-      # @param [String] page
-      #   The man page file name.
+      # @param [String] man_page
+      #   The file name of the man page to display.
       #
       # @return [Boolean, nil]
       #   Specifies whether the `man` command was successful or not.
       #   Returns `nil` when the `man` command is not installed.
       #
-      def man(page=man_page)
-        system('man',page)
+      # @raise [NotImplementedError]
+      #   {ClassMethods#man_dir .man_dir} does not have a value.
+      #
+      # @api semipublic
+      #
+      def help_man(man_page=self.class.man_page)
+        unless self.class.man_dir
+          raise(NotImplementedError,"#{self.class}.man_dir not set")
+        end
+
+        man_path = File.join(self.class.man_dir,man_page)
+
+        man(man_path)
       end
 
       #
-      # Displays the {#man_page} instead of the usual `--help` output.
+      # Displays the {ClassMethods#man_page .man_page} in
+      # {ClassMethods#man_dir .man_dir} instead of the usual `--help` output.
       #
       # @raise [NotImplementedError]
-      #   {ClassMethods#man_dir man_dir} does not have a value.
+      #   {ClassMethods#man_dir .man_dir} does not have a value.
       #
       # @note
-      #   if `TERM` is `dumb` or `$stdout` is not a TTY, fallsback to printing
-      #   the usual `--help` output.
+      #   if `TERM` is `dumb` or `$stdout` is not a TTY, will fall back to
+      #   printing the usual `--help` output.
+      #
+      # @api public
       #
       def help
-        if Man.supported?
-          unless self.class.man_dir
-            raise(NotImplementedError,"#{self.class}.man_dir not set")
-          end
-
-          man_path = File.join(self.class.man_dir,man_page)
-
-          if man(man_path).nil?
+        if stdout.tty?
+          if help_man.nil?
+            # the `man` command is not installed
             super
           end
         else

data/lib/command_kit/help.rb

@@ -15,6 +15,9 @@ module CommandKit
   #     MyCmd.help
   #
   module Help
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether {Help}
@@ -36,6 +39,9 @@ module CommandKit
 
     extend ModuleMethods
 
+    #
+    # Class-level methods.
+    #
     module ClassMethods
       #
       # Prints `--help` information.
@@ -45,6 +51,8 @@ module CommandKit
       #
       # @see Help#help
       #
+      # @api public
+      #
       def help(**kwargs)
         new(**kwargs).help
       end
@@ -55,8 +63,9 @@ module CommandKit
     #
     # @abstract
     #
+    # @api public
+    #
     def help
-      super if defined?(super)
     end
   end
 end

data/lib/command_kit/inflector.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'strscan'
+
 module CommandKit
   #
   # A very simple inflector.
@@ -8,6 +10,8 @@ module CommandKit
   #   If you need something more powerful, checkout
   #   [dry-inflector](https://dry-rb.org/gems/dry-inflector/0.1/)
   #
+  # @api semipublic
+  #
   module Inflector
     #
     # Removes the namespace from a constant name.
@@ -31,16 +35,37 @@ module CommandKit
     # @return [String]
     #   The resulting under_scored name.
     #
+    # @raise [ArgumentError]
+    #   The given string contained non-alpha-numeric characters.
+    #
     def self.underscore(name)
-      # sourced from: https://github.com/dry-rb/dry-inflector/blob/c918f967ff82611da374eb0847a77b7e012d3fa8/lib/dry/inflector.rb#L286-L287
-      name = name.to_s.dup
+      scanner    = StringScanner.new(name.to_s)
+      new_string = String.new
 
-      name.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
-      name.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
-      name.tr!('-','_')
-      name.downcase!
+      until scanner.eos?
+        if (separator = scanner.scan(/[_-]+/))
+          new_string << '_' * separator.length
+        else
+          if (capitalized = scanner.scan(/[A-Z][a-z\d]+/))
+            new_string << capitalized
+          elsif (uppercase = scanner.scan(/[A-Z][A-Z\d]*(?=[A-Z_-]|$)/))
+            new_string << uppercase
+          elsif (lowercase = scanner.scan(/[a-z][a-z\d]*/))
+            new_string << lowercase
+          else
+            raise(ArgumentError,"cannot convert string to underscored: #{scanner.string.inspect}")
+          end
 
-      name
+          if (separator = scanner.scan(/[_-]+/))
+            new_string << '_' * separator.length
+          elsif !scanner.eos?
+            new_string << '_'
+          end
+        end
+      end
+
+      new_string.downcase!
+      new_string
     end
 
     #
@@ -65,20 +90,27 @@ module CommandKit
     # @return [String]
     #   The CamelCased name.
     #
+    # @raise [ArgumentError]
+    #   The given under_scored string contained non-alpha-numeric characters.
+    #
     def self.camelize(name)
-      name = name.to_s.dup
-
-      # sourced from: https://github.com/dry-rb/dry-inflector/blob/c918f967ff82611da374eb0847a77b7e012d3fa8/lib/dry/inflector.rb#L329-L334
-      name.sub!(/^[a-z\d]*/,&:capitalize)
-      name.gsub!(%r{(?:[_-]|(/))([a-z\d]*)}i) do |match|
-        slash = Regexp.last_match(1)
-        word  = Regexp.last_match(2)
+      scanner    = StringScanner.new(name.to_s)
+      new_string = String.new
 
-        "#{slash}#{word.capitalize}"
+      until scanner.eos?
+        if (word = scanner.scan(/[A-Za-z\d]+/))
+          word.capitalize!
+          new_string << word
+        elsif scanner.scan(/[_-]+/)
+          # skip
+        elsif scanner.scan(/\//)
+          new_string << '::'
+        else
+          raise(ArgumentError,"cannot convert string to CamelCase: #{scanner.string.inspect}")
+        end
       end
 
-      name.gsub!('/','::')
-      name
+      new_string
     end
   end
 end

data/lib/command_kit/interactive.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require 'command_kit/stdio'
+
+module CommandKit
+  #
+  # Provides methods for asking the user for input.
+  #
+  # ## Examples
+  #
+  #     first_name = ask("First name")
+  #     last_name = ask("Last name")
+  #
+  # ### Asking for secret input
+  #
+  #     password = ask_secret("Password")
+  #
+  # ### Asking Y/N?
+  #
+  #     if ask_yes_or_no("Proceed anyways?")
+  #       # ...
+  #     else
+  #       stderr.puts "Aborting!"
+  #     end
+  #
+  # ### Asking multi-choice questions
+  #
+  #     ask_multiple_choice("Select a flavor", %w[Apple Orange Lemon Lime])
+  #     #   1) Apple
+  #     #   2) Orange
+  #     #   3) Lemon
+  #     #   4) Lime
+  #     #   Select a flavor: 4
+  #     #
+  #     # => "Lime"
+  #
+  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.
+    #
+    # @example
+    #   first_name = ask("First name")
+    #   last_name = ask("Last name")
+    #
+    # @example Default value:
+    #   ask("Country", default: "EU")
+    #   # Country [EU]: <enter>
+    #   # => "EU"
+    #
+    # @example Required non-empty input:
+    #   ask("Email", required: true)
+    #   # Email: <enter>
+    #   # Email: bob@example.com<enter>
+    #   # => "bob@example.com"
+    #
+    # @api public
+    #
+    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
+    #   # => true
+    #
+    # @example Default value:
+    #   ask_yes_or_no("Proceed anyways?", default: true)
+    #   # Proceed anyways? (Y/N) [Y]: <enter>
+    #   # => true
+    #
+    # @api public
+    #
+    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"
+    #
+    # @api public
+    #
+    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"
+    #
+    # @api public
+    #
+    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