command_kit 0.1.0.pre1 → 0.2.0

data/lib/command_kit/command_name.rb

@@ -31,6 +31,9 @@ module CommandKit
   #     # => "foo-cmd"
   #
   module CommandName
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -65,6 +68,8 @@ module CommandKit
       #
       # @return [String]
       #
+      # @api public
+      #
       def command_name(new_command_name=nil)
         if new_command_name
           @command_name = new_command_name.to_s
@@ -77,6 +82,8 @@ module CommandKit
     # The commands name.
     #
     # @return [String]
+    #
+    # @api public
     attr_reader :command_name
 
     #
@@ -86,6 +93,8 @@ module CommandKit
     #   Overrides the command name. Defaults to
     #   {ClassMethods#command_name self.class.command_name}.
     #
+    # @api public
+    #
     def initialize(command_name: self.class.command_name, **kwargs)
       @command_name = command_name
 

data/lib/command_kit/commands/auto_load/subcommand.rb

@@ -3,6 +3,9 @@ require 'command_kit/commands/subcommand'
 module CommandKit
   module Commands
     class AutoLoad < Module
+      #
+      # Represents a registered subcommand that will be auto-loaded.
+      #
       class Subcommand < Commands::Subcommand
 
         # The fully qualified constant of the command class.

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,6 +158,8 @@ module CommandKit
       # @param [Class] command
       #   The command class including {AutoLoad}.
       #
+      # @api private
+      #
       def included(command)
         command.include Commands
         command.commands.merge!(@commands)

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,6 +8,8 @@ module CommandKit
     #
     # The default help command.
     #
+    # @api semipublic
+    #
     class Help < Command
 
       include ParentCommand

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

@@ -1,5 +1,10 @@
 module CommandKit
   module Commands
+    #
+    # Represents a registered subcommand.
+    #
+    # @api private
+    #
     class Subcommand
 
       # The command class.
@@ -37,6 +42,16 @@ module CommandKit
         @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
@@ -73,13 +76,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 +93,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,6 +132,8 @@ 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
@@ -145,8 +154,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
@@ -158,6 +171,14 @@ module CommandKit
       end
     end
 
+    #
+    # Initializes the command.
+    #
+    # @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)
 
@@ -175,6 +196,8 @@ module CommandKit
     # @return [Object#main, nil]
     #   The initialized subcommand.
     #
+    # @api private
+    #
     def command(name)
       unless (command_class = self.class.get_command(name))
         return
@@ -219,6 +242,8 @@ module CommandKit
     # @return [Integer]
     #   The exit status of the command.
     #
+    # @api semipublic
+    #
     def invoke(name,*argv)
       if (command = command(name))
         command.main(argv)
@@ -231,6 +256,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`"
@@ -250,6 +278,8 @@ module CommandKit
     #
     # @see command_not_found
     #
+    # @api semipublic
+    #
     def on_unknown_command(name,argv=[])
       command_not_found(name)
     end
@@ -259,6 +289,8 @@ 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)
@@ -270,6 +302,8 @@ module CommandKit
     #
     # Prints the available commands and their summaries.
     #
+    # @api semipublic
+    #
     def help_commands
       unless self.class.commands.empty?
         puts
@@ -290,6 +324,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,11 +53,15 @@ module CommandKit
       # @example
       #   description "Does things and stuff"
       #
+      # @api public
+      #
       def description(new_description=nil)
         if new_description
           @description = new_description
         else
-          @description || (superclass.description if superclass.kind_of?(ClassMethods))
+          @description || if superclass.kind_of?(ClassMethods)
+                            superclass.description
+                          end
         end
       end
     end
@@ -62,6 +69,8 @@ module CommandKit
     #
     # @see ClassMethods#description
     #
+    # @api semipublic
+    #
     def description
       self.class.description
     end
@@ -69,6 +78,8 @@ module CommandKit
     #
     # Prints the {ClassMethods#description description}, if set.
     #
+    # @api semipublic
+    #
     def help_description
       if (description = self.description)
         puts
@@ -80,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)