command_kit 0.1.0.rc1 → 0.2.2

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}.
@@ -122,11 +110,13 @@ module CommandKit
       #   Returns `nil` when the `man` command is not installed.
       #
       # @raise [NotImplementedError]
-      #   {ClassMethods#man_dir .man_dir} does not have a value.
+      #   {ClassMethods#man_dir .man_dir} was not set in the class.
+      #
+      # @api semipublic
       #
       def help_man(man_page=self.class.man_page)
         unless self.class.man_dir
-          raise(NotImplementedError,"#{self.class}.man_dir not set")
+          raise(NotImplementedError,"man_dir was not set in #{self.class}")
         end
 
         man_path = File.join(self.class.man_dir,man_page)
@@ -138,20 +128,27 @@ module CommandKit
       # 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.
-      #
       # @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

@@ -1,6 +1,39 @@
+# 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
 
@@ -19,6 +52,23 @@ module CommandKit
     # @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
@@ -56,7 +106,14 @@ module CommandKit
     # @example
     #   ask_yes_or_no("Proceed anyways?")
     #   # Proceed anyways? (Y/N): Y
-    #   # => :yes
+    #   # => 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
@@ -123,6 +180,8 @@ module CommandKit
     #   #
     #   # => "All of the above"
     #
+    # @api public
+    #
     def ask_multiple_choice(prompt,choices,**kwargs)
       choices = case choices
                 when Array
@@ -159,11 +218,22 @@ module CommandKit
     #
     # 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

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]
       #

data/lib/command_kit/options/option_value.rb

@@ -14,6 +14,8 @@ module CommandKit
     #
     # Represents an additional argument associated with an option flag.
     #
+    # @api private
+    #
     class OptionValue < Arguments::ArgumentValue
 
       # Maps OptionParser types to USAGE strings.
@@ -39,7 +41,7 @@ module CommandKit
 
       # The desired type of the argument value.
       #
-      # @return [Class, Hash, Array, Regexp, nil]
+      # @return [Class, Hash, Array, Regexp]
       attr_reader :type
 
       # The default parsed value for the argument value.
@@ -90,10 +92,11 @@ module CommandKit
       def self.default_usage(type)
         USAGES.fetch(type) do
           case type
-          when Class  then Inflector.underscore(type.name).upcase
           when Hash   then type.keys.join('|')
           when Array  then type.join('|')
           when Regexp then type.source
+          when Class
+            Inflector.underscore(Inflector.demodularize(type.name)).upcase
           else
             raise(TypeError,"unsupported option type: #{type.inspect}")
           end