command_kit 0.1.0 → 0.3.0

data/lib/command_kit/command.rb

@@ -8,8 +8,7 @@ require 'command_kit/options'
 require 'command_kit/examples'
 require 'command_kit/description'
 require 'command_kit/exception_handler'
-
-require 'fileutils'
+require 'command_kit/file_utils'
 
 module CommandKit
   #
@@ -56,7 +55,7 @@ module CommandKit
   #       end
   #     end
   #
-  # ### initialize and using ivars
+  # ### initialize and using instance variables
   #
   #     option :verbose, short: '-v', desc: "Increase verbose level" do
   #       @verbose += 1

data/lib/command_kit/commands/auto_load.rb

@@ -162,7 +162,14 @@ module CommandKit
       #
       def included(command)
         command.include Commands
-        command.commands.merge!(@commands)
+
+        @commands.each do |name,subcommand|
+          command.commands[name] = subcommand
+
+          subcommand.aliases.each do |alias_name|
+            command.command_aliases[alias_name] = name
+          end
+        end
       end
     end
   end

data/lib/command_kit/commands/help.rb

@@ -14,7 +14,8 @@ module CommandKit
 
       include ParentCommand
 
-      argument :command, desc: 'Command name to lookup'
+      argument :command, required: false,
+                         desc: 'Command name to lookup'
 
       #
       # Prints the given commands `--help` output or lists registered commands.
@@ -34,7 +35,7 @@ module CommandKit
 
             subcommand.help
           else
-            print_error "#{command_name}: unknown command: #{command}"
+            print_error "unknown command: #{command}"
             exit(1)
           end
         end

data/lib/command_kit/commands/subcommand.rb

@@ -36,7 +36,7 @@ module CommandKit
       #   Optional alias names for the subcommand.
       #
       def initialize(command, summary: self.class.summary(command),
-                                   aliases: [])
+                              aliases: [])
         @command = command
         @summary = summary
         @aliases = aliases.map(&:to_s)

data/lib/command_kit/commands.rb

@@ -59,6 +59,13 @@ module CommandKit
           context.extend ModuleMethods
         else
           context.usage "[options] [COMMAND [ARGS...]]"
+          context.argument :command, required: false,
+                                     desc: 'The command name to run'
+
+          context.argument :args, required: false,
+                                  repeats: true,
+                                  desc: 'Additional arguments for the command'
+
           context.extend ClassMethods
           context.command Help
         end
@@ -81,10 +88,10 @@ module CommandKit
       # 
       def commands
         @commands ||= if superclass.kind_of?(ClassMethods)
-                         superclass.commands.dup
-                       else
-                         {}
-                       end
+                        superclass.commands.dup
+                      else
+                        {}
+                      end
       end
 
       #
@@ -140,11 +147,10 @@ module CommandKit
                end
 
         subcommand = Subcommand.new(command_class,**kwargs)
-
         commands[name] = subcommand
 
-        subcommand.aliases.each do |command_alias|
-          command_aliases[command_alias] = name
+        subcommand.aliases.each do |alias_name|
+          command_aliases[alias_name] = name
         end
 
         return subcommand
@@ -220,7 +226,9 @@ module CommandKit
       end
 
       if command_class.include?(Env)
-        kwargs[:env] = env.dup
+        kwargs[:env] = if env.eql?(ENV) then env.to_h
+                       else                  env.dup
+                       end
       end
 
       if command_class.include?(Options)
@@ -296,6 +304,7 @@ module CommandKit
         exit invoke(command,*argv)
       else
         help
+        exit(1)
       end
     end
 
@@ -309,8 +318,14 @@ module CommandKit
         puts
         puts "Commands:"
 
+        command_aliases = Hash.new { |hash,key| hash[key] = [] }
+
+        self.class.command_aliases.each do |alias_name,name|
+          command_aliases[name] << alias_name
+        end
+
         self.class.commands.sort.each do |name,subcommand|
-          names = [name, *subcommand.aliases].join(', ')
+          names = [name, *command_aliases[name]].join(', ')
 
           if subcommand.summary
             puts "    #{names}\t#{subcommand.summary}"

data/lib/command_kit/env/path.rb

@@ -16,7 +16,7 @@ module CommandKit
 
       # The home directory.
       #
-      # @return [String]
+      # @return [Array<String>]
       #
       # @api semipublic
       attr_reader :path_dirs

data/lib/command_kit/file_utils.rb

@@ -0,0 +1,46 @@
+require 'fileutils'
+require 'erb'
+
+module CommandKit
+  #
+  # File manipulation related methods.
+  #
+  # @since 0.3.0
+  #
+  # @api public
+  #
+  module FileUtils
+    include ::FileUtils
+
+    #
+    # Renders an erb file and optionally writes it out to a destination file.
+    #
+    # @param [String] source
+    #   The path to the erb template file.
+    #
+    # @param [String, nil] dest
+    #   The path to the destination file.
+    #
+    # @return [String, nil]
+    #   If no destination path argument is given, the rendered erb template
+    #   String will be returned.
+    #
+    # @example Rendering a ERB template and saving it's output:
+    #   erb File.join(template_dir,'README.md.erb'), 'README.md'
+    #
+    # @example Rendering a ERB template and capturing it's output:
+    #   output = erb(File.join(template_dir,'_partial.erb'))
+    #
+    def erb(source,dest=nil)
+      erb    = ERB.new(File.read(source), trim_mode: '-')
+      result = erb.result(binding)
+
+      if dest
+        File.write(dest,result)
+        return
+      else
+        return result
+      end
+    end
+  end
+end

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,6 +24,7 @@ module CommandKit
       include CommandName
       include Help
       include Stdio
+      include CommandKit::Man
 
       #
       # @api private
@@ -68,7 +70,7 @@ module CommandKit
         #
         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
@@ -96,29 +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.
-      #
-      # @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
-
       #
       # Provides help information by showing one of the man pages within
       # {ClassMethods#man_dir .man_dir}.
@@ -131,13 +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)
@@ -149,22 +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/inflector.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'strscan'
+
 module CommandKit
   #
   # A very simple inflector.
@@ -33,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
+
+      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.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
-      name.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
-      name.tr!('-','_')
-      name.downcase!
+          if (separator = scanner.scan(/[_-]+/))
+            new_string << ('_' * separator.length)
+          elsif !scanner.eos?
+            new_string << '_'
+          end
+        end
+      end
 
-      name
+      new_string.downcase!
+      new_string
     end
 
     #
@@ -67,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

@@ -218,6 +218,15 @@ 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: 

data/lib/command_kit/main.rb

@@ -49,15 +49,13 @@ module CommandKit
       # @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
 
       #

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

@@ -35,16 +35,18 @@ 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]
       attr_reader :block
 
+      # The optional category to group the option under.
+      #
+      # @return [String, nil]
+      #
+      # @since 0.3.0
+      attr_reader :category
+
       #
       # Initializes the option.
       #
@@ -70,9 +72,12 @@ module CommandKit
       # @option value [String, nil] usage
       #   The usage string for the option's value.
       #
-      # @param [String] desc
+      # @param [String, Array<String>] desc
       #   The description for the option.
       #
+      # @param [String, nil] category
+      #   The optional category to group the option under.
+      #
       # @yield [(value)]
       #   If a block is given, it will be called when the option is parsed.
       #
@@ -83,25 +88,27 @@ module CommandKit
       #   The `value` keyword argument was not a `Hash`, `true`, `false`, or
       #   `nil`.
       #
-      def initialize(name, short:   nil,
-                           long:    self.class.default_long_opt(name),
-                           equals:  false,
-                           value:   nil,
-                           desc:    ,
+      def initialize(name, short:    nil,
+                           long:     self.class.default_long_opt(name),
+                           equals:   false,
+                           value:    nil,
+                           desc:     ,
+                           category: nil,
                            &block)
-        @name    = name
-        @short   = short
-        @long    = long
-        @equals  = equals
-        @value   = case value
-                   when Hash       then OptionValue.new(**value)
-                   when true       then OptionValue.new()
-                   when false, nil then nil
-                   else
-                     raise(TypeError,"value: keyword must be Hash, true, false, or nil")
-                   end
-        @desc    = desc
-        @block   = block
+        @name     = name
+        @short    = short
+        @long     = long
+        @equals   = equals
+        @value    = case value
+                    when Hash       then OptionValue.new(**value)
+                    when true       then OptionValue.new()
+                    when false, nil then nil
+                    else
+                      raise(TypeError,"value: keyword must be Hash, true, false, or nil")
+                    end
+        @desc     = desc
+        @category = category
+        @block    = block
       end
 
       #
@@ -128,7 +135,7 @@ module CommandKit
       end
 
       #
-      # The separator characer between the option and option value.
+      # The separator character between the option and option value.
       #
       # @return ['=', ' ', nil]
       #
@@ -184,7 +191,7 @@ module CommandKit
       #
       # The option description.
       #
-      # @return [String]
+      # @return [String, Array<String>]
       #
       # @note
       #   If {#default_value} returns a value, the description will contain the
@@ -192,7 +199,14 @@ module CommandKit
       #
       def desc
         if (value = default_value)
-          "#{@desc} (Default: #{value})"
+          default_text = "(Default: #{value})"
+
+          case @desc
+          when Array
+            @desc + [default_text]
+          else
+            "#{@desc} #{default_text}"
+          end
         else
           @desc
         end

data/lib/command_kit/options/option_value.rb

@@ -41,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.
@@ -92,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