command_kit 0.1.0.pre2 → 0.2.1

data/lib/command_kit/help/man.rb

@@ -3,6 +3,7 @@
 require 'command_kit/command_name'
 require 'command_kit/help'
 require 'command_kit/stdio'
+require 'command_kit/man'
 
 module CommandKit
   module Help
@@ -23,7 +24,11 @@ module CommandKit
       include CommandName
       include Help
       include Stdio
+      include CommandKit::Man
 
+      #
+      # @api private
+      #
       module ModuleMethods
         #
         # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -61,9 +66,11 @@ module CommandKit
         # @example
         #   man_dir "#{__dir__}/../../man"
         #
+        # @api public
+        #
         def man_dir(new_man_dir=nil)
           if new_man_dir
-            @man_dir = new_man_dir
+            @man_dir = File.expand_path(new_man_dir)
           else
             @man_dir || if superclass.kind_of?(ClassMethods)
                           superclass.man_dir
@@ -80,6 +87,8 @@ module CommandKit
         # @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
@@ -89,27 +98,6 @@ module CommandKit
         end
       end
 
-      #
-      # Displays the given man page.
-      #
-      # @param [String] page
-      #   The man page file name.
-      #
-      # @param [Integer, String, nil] section
-      #   The optional section number to specify.
-      #
-      # @return [Boolean, nil]
-      #   Specifies whether the `man` command was successful or not.
-      #   Returns `nil` when the `man` command is not installed.
-      #
-      def man(page, section: nil)
-        if section
-          system('man',section.to_s,page.to_s)
-        else
-          system('man',page.to_s)
-        end
-      end
-
       #
       # Provides help information by showing one of the man pages within
       # {ClassMethods#man_dir .man_dir}.
@@ -124,11 +112,9 @@ module CommandKit
       # @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)
@@ -142,16 +128,26 @@ module CommandKit
       #   {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 stdout.tty?
-          if help_man.nil?
-            # the `man` command is not installed
+          if self.class.man_dir
+            status = help_man
+
+            if status.nil?
+              # the `man` command is not installed
+              super
+            end
+          else
+            # man_dir was not set
             super
           end
         else
+          # stdout is not a TTY
           super
         end
       end

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}
@@ -48,6 +51,8 @@ module CommandKit
       #
       # @see Help#help
       #
+      # @api public
+      #
       def help(**kwargs)
         new(**kwargs).help
       end
@@ -58,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,248 @@
+# 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.
+    #
+    # @param [String] prompt
+    #   The prompt that will be printed before reading input.
+    #
+    # @param [Boolean] required
+    #   Requires non-empty input.
+    #
+    # @return [String]
+    #   The user 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

data/lib/command_kit/main.rb

@@ -12,6 +12,9 @@ module CommandKit
   #     end
   #
   module Main
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether {Main}
@@ -43,16 +46,16 @@ module CommandKit
       # @param [Array<String>] argv
       #   The Array of command-line arguments.
       #
+      # @api public
+      #
       def start(argv=ARGV, **kwargs)
-        begin
-          exit main(argv, **kwargs)
-        rescue Interrupt
-          # https://tldp.org/LDP/abs/html/exitcodes.html
-          exit 130
-        rescue Errno::EPIPE
-          # STDOUT pipe broken
-          exit 0
-        end
+        exit main(argv, **kwargs)
+      rescue Interrupt
+        # https://tldp.org/LDP/abs/html/exitcodes.html
+        exit 130
+      rescue Errno::EPIPE
+        # STDOUT pipe broken
+        exit 0
       end
 
       #
@@ -68,6 +71,8 @@ module CommandKit
       # @return [Integer]
       #   The exit status of the command.
       #
+      # @api public
+      #
       def main(argv=[], **kwargs)
         new(**kwargs).main(argv)
       end
@@ -84,6 +89,8 @@ module CommandKit
     #
     # @note `argv` is splatted into {#run}.
     #
+    # @api public
+    #
     def main(argv=[])
       run(*argv)
       return 0
@@ -99,6 +106,8 @@ module CommandKit
     #   
     # @abstract
     #
+    # @api public
+    #
     def run(*args)
     end
   end

data/lib/command_kit/man.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module CommandKit
+  #
+  # Allows displaying man pages.
+  #
+  # ## Examples
+  #
+  #     man "passwd"
+  #     man "passwd", section: 5
+  #
+  # @since 0.2.0
+  #
+  module Man
+    #
+    # Displays the given man page.
+    #
+    # @param [String] page
+    #   The man page file name.
+    #
+    # @param [Integer, String, nil] section
+    #   The optional section number to specify.
+    #
+    # @return [Boolean, nil]
+    #   Specifies whether the `man` command was successful or not.
+    #   Returns `nil` when the `man` command is not installed.
+    #
+    # @example
+    #   man "passwd"
+    #
+    # @example Display a man-page from a specific section:
+    #   man "passwd", section: 5
+    #
+    # @api public
+    #
+    def man(page, section: nil)
+      if section
+        system('man',section.to_s,page.to_s)
+      else
+        system('man',page.to_s)
+      end
+    end
+  end
+end

data/lib/command_kit/open_app.rb

@@ -0,0 +1,69 @@
+require 'command_kit/os'
+require 'command_kit/env/path'
+
+module CommandKit
+  #
+  # Allows opening a file or a URI with the system's preferred application for
+  # that file type or URI scheme.
+  #
+  # ## Examples
+  #
+  #     open_app_for "movie.avi"
+  #     open_app_for "https://github.com/postmodern/command_kit.rb#readme"
+  #
+  # @since 0.2.0
+  #
+  module OpenApp
+    include OS
+    include Env::Path
+
+    #
+    # Initializes the command and determines which open command to use.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @api public
+    #
+    def initialize(**kwargs)
+      super(**kwargs)
+
+      @open_command = if macos?
+                        'open'
+                      elsif linux? || bsd?
+                        if command_installed?('xdg-open')
+                          'xdg-open'
+                        end
+                      elsif windows?
+                        if command_installed?('invoke-item')
+                          'invoke-item'
+                        else
+                          'start'
+                        end
+                      end
+    end
+
+    #
+    # Opens a file or URI using the system's preferred application for that
+    # file type or URI scheme.
+    #
+    # @param [String, URI] file_or_uri
+    #   The file path or URI to open.
+    #
+    # @return [Boolean, nil]
+    #   Specifies whether the file or URI was successfully opened or not.
+    #   If the open command could not be determined, `nil` is returned.
+    #
+    # @example Open a file:
+    #   open_app_for "movie.avi"
+    #
+    # @example Open a URI:
+    #   open_app_for "https://github.com/postmodern/command_kit.rb"
+    #
+    def open_app_for(file_or_uri)
+      if @open_command
+        system(@open_command,file_or_uri.to_s)
+      end
+    end
+  end
+end

data/lib/command_kit/options/option.rb

@@ -11,6 +11,8 @@ module CommandKit
     #
     # Represents a defined option.
     #
+    # @api private
+    #
     class Option
 
       # The option's name.
@@ -33,11 +35,6 @@ module CommandKit
       # @return [OptionValue, nil]
       attr_reader :value
 
-      # The option's description.
-      #
-      # @return [String]
-      attr_reader :desc
-
       # The optional block that will receive the parsed option value.
       #
       # @return [Proc, nil]
@@ -126,7 +123,7 @@ module CommandKit
       end
 
       #
-      # The separator characer between the option and option value.
+      # The separator character between the option and option value.
       #
       # @return ['=', ' ', nil]
       #