command_kit 0.1.0.pre2 → 0.2.1

data/lib/command_kit/commands/auto_load.rb

@@ -40,16 +40,22 @@ module CommandKit
       # The auto-load subcommands.
       #
       # @return [Hash{String => Subcommand}]
+      #
+      # @api private
       attr_reader :commands
 
       # The path to the directory containing the command files.
       #
       # @return [String]
+      #
+      # @api private
       attr_reader :dir
 
       # The namespace that the will contain the command classes.
       #
       # @return [String]
+      #
+      # @api private
       attr_reader :namespace
 
       #
@@ -65,6 +71,8 @@ module CommandKit
       #   If a block is given, it will be used to explicitly map the files
       #   within {#dir} as commands.
       #
+      # @api public
+      #
       def initialize(dir: , namespace: )
         @commands  = {}
 
@@ -106,6 +114,8 @@ module CommandKit
       # @option kwargs [Array<String>] aliases
       #   Optional alias names for the subcommand.
       #
+      # @api public
+      #
       def command(name, constant, file, **kwargs)
         @commands[name.to_s] = Subcommand.new(
           "#{@namespace}::#{constant}",
@@ -123,6 +133,8 @@ module CommandKit
       # @return [String]
       #   The joined absolute path.
       #
+      # @api private
+      #
       def join(path)
         File.join(@dir,path)
       end
@@ -133,6 +145,8 @@ module CommandKit
       # @return [Array<String>]
       #   The paths to the `.rb` files in the directory.
       #
+      # @api private
+      #
       def files
         Dir.glob(join('*.rb'))
       end
@@ -144,9 +158,18 @@ module CommandKit
       # @param [Class] command
       #   The command class including {AutoLoad}.
       #
+      # @api private
+      #
       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/auto_require.rb

@@ -27,11 +27,15 @@ module CommandKit
       # The directory to attempt to require command files within.
       #
       # @return [String]
+      #
+      # @api private
       attr_reader :dir
 
       # The namespace to lookup command classes within.
       #
       # @return [String]
+      #
+      # @api private
       attr_reader :namespace
 
       #
@@ -43,6 +47,8 @@ module CommandKit
       # @param [String] namespace
       #   The namespace to search for command classes in.
       #
+      # @api public
+      #
       def initialize(dir: , namespace: )
         @dir       = dir
         @namespace = namespace
@@ -57,6 +63,8 @@ module CommandKit
       # @return [String]
       #   The path to the file that should contain the command.
       #
+      # @api private
+      #
       def join(name)
         File.join(@dir,name)
       end
@@ -70,6 +78,8 @@ module CommandKit
       #
       # @raise [LoadError]
       #
+      # @api private
+      #
       def require(file_name)
         super(join(file_name))
       end
@@ -86,6 +96,8 @@ module CommandKit
       # @raise [NameError]
       #   The command class could not be found within the {#namespace}.
       #
+      # @api private
+      #
       def const_get(constant)
         Object.const_get("::#{@namespace}::#{constant}",false)
       end
@@ -100,6 +112,8 @@ module CommandKit
       #   The command's class, or `nil` if the command cannot be loaded from
       #   {#dir} or found within {#namespace}.
       #
+      # @api private
+      #
       def command(command_name)
         file_name = Inflector.underscore(command_name)
 
@@ -125,6 +139,8 @@ module CommandKit
       # @param [Class] command
       #   The command class including {AutoRequire}.
       #
+      # @api private
+      #
       def included(command)
         command.include Commands
         command.commands.default_proc = ->(hash,key) {

data/lib/command_kit/commands/command.rb

@@ -3,6 +3,9 @@ require 'command_kit/commands/parent_command'
 
 module CommandKit
   module Commands
+    #
+    # @api public
+    #
     class Command < CommandKit::Command
 
       include ParentCommand

data/lib/command_kit/commands/help.rb

@@ -8,11 +8,14 @@ module CommandKit
     #
     # The default help command.
     #
+    # @api semipublic
+    #
     class Help < Command
 
       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.
@@ -32,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/parent_command.rb

@@ -1,15 +1,22 @@
 module CommandKit
   module Commands
+    #
+    # Allows a command to be aware of it's parent command.
+    #
     module ParentCommand
 
       # The parent command instance.
       #
       # @return [Object<Commands>]
+      #
+      # @api semipublic
       attr_reader :parent_command
 
       #
       # Initializes the command and sets {#parent_command}.
       #
+      # @api public
+      #
       def initialize(parent_command: , **kwargs)
         @parent_command = parent_command
 

data/lib/command_kit/commands/subcommand.rb

@@ -3,6 +3,8 @@ module CommandKit
     #
     # Represents a registered subcommand.
     #
+    # @api private
+    #
     class Subcommand
 
       # The command class.
@@ -34,12 +36,22 @@ 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)
       end
 
+      #
+      # Derives a summary from the command's description.
+      #
+      # @param [Class] command
+      #   The command class.
+      #
+      # @return [String, nil]
+      #   If the command responds to a `#description` method, the first sentence
+      #   of the description will be returned. Otherwise `nil` is returned.
+      #
       def self.summary(command)
         if command.respond_to?(:description)
           if (desc = command.description)

data/lib/command_kit/commands.rb

@@ -41,6 +41,9 @@ module CommandKit
     include Stdio
     include Env
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -56,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
@@ -73,13 +83,15 @@ module CommandKit
       #
       # @return [Hash{String => Subcommand}]
       #   The Hash of sub-command names and command classes.
+      #
+      # @api semipublic
       # 
       def commands
         @commands ||= if superclass.kind_of?(ClassMethods)
-                         superclass.commands.dup
-                       else
-                         {}
-                       end
+                        superclass.commands.dup
+                      else
+                        {}
+                      end
       end
 
       #
@@ -88,6 +100,8 @@ module CommandKit
       # @return [Hash{String => String}]
       #   The Hash of command aliases to primary command names.
       # 
+      # @api semipublic
+      #
       def command_aliases
         @command_aliases ||= if superclass.kind_of?(ClassMethods)
                                superclass.command_aliases.dup
@@ -125,17 +139,18 @@ module CommandKit
       # @example
       #   command 'foo-bar', FooBar
       #
+      # @api public
+      #
       def command(name=nil, command_class, **kwargs)
         name = if name then name.to_s
                else         command_class.command_name
                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
@@ -145,8 +160,12 @@ module CommandKit
       # Gets the command.
       #
       # @param [String] name
+      #   The command name.
       #
       # @return [Class#main, nil]
+      #   The command class or `nil` if no command could be found.
+      #
+      # @api private
       #
       def get_command(name)
         name = name.to_s
@@ -164,6 +183,8 @@ module CommandKit
     # @note Adds a special rule to the {Options#option_parser #option_parser} to
     # stop parsing options when the first non-option is encountered.
     #
+    # @api public
+    #
     def initialize(**kwargs)
       super(**kwargs)
 
@@ -181,6 +202,8 @@ module CommandKit
     # @return [Object#main, nil]
     #   The initialized subcommand.
     #
+    # @api private
+    #
     def command(name)
       unless (command_class = self.class.get_command(name))
         return
@@ -203,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)
@@ -225,6 +250,8 @@ module CommandKit
     # @return [Integer]
     #   The exit status of the command.
     #
+    # @api semipublic
+    #
     def invoke(name,*argv)
       if (command = command(name))
         command.main(argv)
@@ -237,6 +264,9 @@ module CommandKit
     # Prints an error about an unknown command and exits with an error code.
     #
     # @param [String] name
+    #   The command name.
+    #
+    # @api semipublic
     #
     def command_not_found(name)
       print_error "'#{name}' is not a #{command_name} command. See `#{command_name} help`"
@@ -256,6 +286,8 @@ module CommandKit
     #
     # @see command_not_found
     #
+    # @api semipublic
+    #
     def on_unknown_command(name,argv=[])
       command_not_found(name)
     end
@@ -265,24 +297,35 @@ module CommandKit
     #
     # @note If no subcommand is given, {#help} will be called.
     #
+    # @api public
+    #
     def run(command=nil,*argv)
       if command
         exit invoke(command,*argv)
       else
         help
+        exit(1)
       end
     end
 
     #
     # Prints the available commands and their summaries.
     #
+    # @api semipublic
+    #
     def help_commands
       unless self.class.commands.empty?
         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}"
@@ -296,6 +339,8 @@ module CommandKit
     #
     # Prints help information and available commands.
     #
+    # @api public
+    #
     def help
       super
 

data/lib/command_kit/description.rb

@@ -13,6 +13,9 @@ module CommandKit
   module Description
     include Help
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -50,6 +53,8 @@ module CommandKit
       # @example
       #   description "Does things and stuff"
       #
+      # @api public
+      #
       def description(new_description=nil)
         if new_description
           @description = new_description
@@ -64,6 +69,8 @@ module CommandKit
     #
     # @see ClassMethods#description
     #
+    # @api semipublic
+    #
     def description
       self.class.description
     end
@@ -71,6 +78,8 @@ module CommandKit
     #
     # Prints the {ClassMethods#description description}, if set.
     #
+    # @api semipublic
+    #
     def help_description
       if (description = self.description)
         puts
@@ -82,8 +91,10 @@ module CommandKit
     # Calls the superclass'es `#help` method, if it's defined, then calls
     # {#help_description}.
     #
+    # @api public
+    #
     def help
-      super if defined?(super)
+      super
 
       help_description
     end

data/lib/command_kit/env/home.rb

@@ -14,6 +14,9 @@ module CommandKit
     module Home
       include Env
 
+      #
+      # @api private
+      #
       module ModuleMethods
         #
         # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -44,6 +47,8 @@ module CommandKit
         #
         # @return [String]
         #
+        # @api semipublic
+        #
         def home_dir
           Gem.user_home
         end
@@ -52,6 +57,8 @@ module CommandKit
       # The home directory.
       #
       # @return [String]
+      #
+      # @api public
       attr_reader :home_dir
 
       #
@@ -61,6 +68,8 @@ module CommandKit
       # @param [Hash{Symbol => Object}] kwargs
       #   Additional keyword arguments.
       #
+      # @api public
+      #
       def initialize(**kwargs)
         super(**kwargs)
 

data/lib/command_kit/env/path.rb

@@ -16,7 +16,9 @@ module CommandKit
 
       # The home directory.
       #
-      # @return [String]
+      # @return [Array<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,6 +60,8 @@ module CommandKit
       #     "-o output.txt path/to/file"
       #   ]
       #   
+      # @api public
+      #
       def examples(new_examples=nil)
         if new_examples
           @examples = Array(new_examples)
@@ -71,6 +76,8 @@ module CommandKit
     #
     # @see ClassMethods#examples
     #
+    # @api semipublic
+    #
     def examples
       self.class.examples
     end
@@ -78,6 +85,8 @@ module CommandKit
     #
     # Prints the command class'es example commands.
     #
+    # @api semipublic
+    #
     def help_examples
       if (examples = self.examples)
         puts
@@ -92,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)