excavator 0.0.1 → 0.0.2

data/lib/excavator/dsl.rb

@@ -1,21 +1,117 @@
+# -*- encoding: utf-8 -*-
+
 module Excavator
-  # Needs to depend on the runner
+
+  # Public: DSL is the primary interface for creating commands. When required,
+  # the global scope is extended with helpers to create namespaces, parameters,
+  # and commands.
+  #
+  # Examples
+  #
+  #   namespace :servers do
+  #     desc "Create a new server"
+  #     param :name, :desc => "Name of the server"
+  #     param :region, :desc => "Region the server is created in"
+  #     command :create do
+  #       # ...
+  #     end
+  #   end
+  #
   module DSL
+
+    # Public: Create a namespace to group commands. Namespaces can be nested.
+    # Namespace names are prefixed to the command name.
+    #
+    # This will create a new namespace if it doesn't exist. All commands defined
+    # within the passed in block are added to the namespace.
+    #
+    # name  - A String or Symbol. This is used as a part of the command name.
+    # block -
+    #
+    # Examples
+    #
+    #   # Creates the command "servers:create"
+    #   namespace :servers do
+    #     command :create do
+    #       # ...
+    #     end
+    #   end
+    #
+    #   # Nesting namespaces
+    #   namespace :public do
+    #     namespace :instances do
+    #       # ...
+    #     end
+    #   end
+    #
+    # Returns nothing.
     def namespace(name)
       Excavator.runner.in_namespace(name) do
         yield
       end
     end
 
+    # Public: Adds a description to the next command declared.
+    #
+    # description - A String describing the command.
+    #
+    # Examples
+    #
+    #   desc "prints hello"
+    #   command :print_hello { ... }
+    #
+    # Returns nothing.
     def desc(description)
       Excavator.runner.last_command.desc = description
     end
 
+    # Public: Add a parameter to the next command declared. This passes all
+    # parameters directly into Param#initialize.
+    #
+    # See the Param and ParamParser class for more details.
+    #
+    # name - A String or Symbol of the parameter name.
+    # options - A Hash of Parameter options (default: {}).
+    #           :desc     - A String describing the parameter.
+    #           :default  - A default value for the parameter.
+    #           :short    - A String (normally one character) to use as the
+    #                       short switch for the parameter. For instance,
+    #                       "param :test, :short => 'c'" will allow
+    #                       the parameter to be used as "-c" on the command
+    #                       line.
+    #           :optional - A Boolean specifying whether the paramter is
+    #                       optional.
+    #
+    # Examples
+    #
+    #   # A required parameter with the long switch "--name"
+    #   param :name
+    #
+    #   # An optional parameter.
+    #   param :name, :optional => true
+    #
+    #   # Set a description.
+    #   param :name, :desc => "A name"
+    #
+    # Returns nothing.
     def param(name, options = {})
       param = Excavator.param_class.new(name, options)
       Excavator.runner.last_command.add_param(param)
     end
 
+    # Public: Creates a command to add to Excavator.runner.
+    #
+    # name - A String or Symbole for the command.
+    # block - A block of code to execute when the command is called. This block
+    #         is executed within an instance of Excavator::Environment.
+    #
+    # Examples
+    #
+    #   command :hello do
+    #     puts "hello"
+    #   end
+    #
+    # Returns a Command.
     def command(name, &block)
       cmd = Excavator.runner.last_command
       cmd.name = name
@@ -29,5 +125,3 @@ module Excavator
 end # Excavator
 
 self.extend Excavator::DSL
-
-

data/lib/excavator/environment.rb

@@ -1,6 +1,33 @@
+# -*- encoding: utf-8 -*-
+
 module Excavator
+
+  # Public: Environment instances are created for a Command's block to execute
+  # in. It is designed for modification and manipulation. Adding other methods
+  # into this class will allow all Commands to reference them.
+  #
+  # Examples
+  #
+  #   module Helpers
+  #     def pretty_logger(msg)
+  #       puts "*~*~*~*"
+  #       puts msg
+  #       puts "*~*~*~*"
+  #     end
+  #   end
+  #
+  #   # Add Helpers to Environment
+  #   Excavator::Environment.modify Helpers
+  #
+  #   param :msg
+  #   command :print do
+  #     # #pretty_logger is now available
+  #     pretty_logger params[:msg]
+  #   end
+  #
   class Environment
 
+    # Public: A convenience method to include other modules in this class.
     def self.modify(*mods, &block)
       mods.each { |m| include m }
       instance_eval &block if block
@@ -15,7 +42,27 @@ module Excavator
       @unparsed_params = options[:unparsed_params]
     end
 
-    # Execute another command
+    # Public: Execute another command. This is a convenience method to execute
+    # other commands defined in Excavator. #execute will return the value
+    # of the executed command (useful for building reusable blocks of code).
+    #
+    # command - A String full name of a command. This should include namespaces.
+    # params  - A Hash of Param name to values to pass to this command.
+    #
+    # Examples
+    #
+    #   namespace :test do
+    #     command :prepare do
+    #       puts params[:foo]
+    #       # => "bar"
+    #     end
+    #
+    #     command :run do
+    #       execute "test:prepare", {:foo => "bar"}
+    #     end
+    #   end
+    #
+    # Returns value from executed command.
     def execute(command, params = {})
       command = runner.find_command(command)
       command.execute(params)

data/lib/excavator/namespace.rb

@@ -1,6 +1,32 @@
+# -*- encoding: utf-8 -*-
+
 module Excavator
+
+  # Internal: Namespace is a container for other Namespaces and Commands.
+  #
+  # Examples
+  #
+  #   ns = Namespace.new
+  #
+  #   # Add a command
+  #   ns << Command.new(:log)
+  #
+  #   # Add a namespace
+  #   ns << Namespace.new(:database)
+  #
+  #   # Lookup a command
+  #   ns.command(:log)
+  #
+  #   # Lookup a namespace
+  #   ns.namespace(:namespace)
+  #
   class Namespace
+
+    # Public: A String/Symbol name for the namespace. This is used to build
+    # a Command's full name used on the command line.
     attr_reader :name
+
+    # Internal: A pointer to the parent Namespace (if any).
     attr_accessor :parent
 
     def initialize(name = nil, options = {})
@@ -9,6 +35,27 @@ module Excavator
       @commands = {}
     end
 
+    # Public: Add a Namespace or Command instance to this namespace.
+    #
+    # When adding namespaces, it will automatically set #parent attribute
+    # on the new object.
+    #
+    # obj - A Command or Namespace to add to the namespace.
+    #
+    # Examples
+    #
+    #   ns = Namespace.new(:test)
+    #
+    #   # Add a namespace. The added namespace will have #parent set to 'ns'.
+    #   recent = Namespace.new(:recent)
+    #   ns << recent
+    #   recent.parent
+    #   # => ns
+    #
+    #   # Add a command.
+    #   ns << Command.new(:name)
+    #
+    # Returns itself (Namespace).
     def <<(obj)
       if self.class === obj
         obj.parent = self
@@ -16,16 +63,74 @@ module Excavator
       else
         @commands[obj.name] = obj
       end
+
+      self
     end
 
+    # Public: Look up a command within this namespace. It does not look into
+    # child namespaces.
+    #
+    # name - A String or Symbol name of the command to look up.
+    #
+    # Examples
+    #
+    #   ns = Namespace.new(:test)
+    #   ns << Command.new(:run)
+    #   ns.command("run")
+    #   # => <Command :run>
+    #
+    # Returns a Command if the command exists in the namespace.
+    # Returns nil if the command does not exist.
     def command(name)
       @commands[name.to_sym]
     end
 
+    # Public: Look up a child namespace within this namespace.
+    #
+    # name - A String or Symbol name of the namespace to look up.
+    #
+    # Examples
+    #
+    #   ns = Namespace.new(:test)
+    #   ns << Namespace.new(:recent)
+    #   ns.namespace(:recent)
+    #   # => <Namespace :recent>
+    #
+    # Returns a Namespace if it exists in the namespace.
+    # Returns nil if the namespace does not exist.
     def namespace(name)
       @namespaces[name.to_sym]
     end
 
+    # Public: The full name of the namespace. This returns a string of the
+    # namespace name and it's ancestor's name joined by ":". A namespace with
+    # no parent will return an emptry String.
+    #
+    # command_name - An optional String or Symbol name of a command to append
+    #                to the end of the namespace's full name.
+    #
+    # Examples
+    #
+    #   ns_a = Namespace.new(:a)
+    #   ns_b = Namespace.new(:b)
+    #   ns_c = Namespace.new(:c)
+    #
+    #   ns_a << ns_b
+    #   ns_b << ns_c
+    #
+    #   ns_a.full_name
+    #   # => ""
+    #
+    #   ns_b.full_name
+    #   # => "a:b"
+    #
+    #   ns_c.full_name
+    #   # => "a:b:c"
+    #
+    #   ns_c.full_name("zebra")
+    #   # => "a:b:c:zebra"
+    #
+    # Returns a String.
     def full_name(command_name = nil)
       return "#{command_name}" if parent.nil?
 
@@ -37,11 +142,35 @@ module Excavator
       parts.compact.join(":")
     end
 
+    # Public: An array of full command names and their description. This will
+    # include all commands in child namespaces as well.
+    #
+    # Examples
+    #
+    #   # Setup
+    #   ns_a = Namespace.new(:a)
+    #   ns_b = Namespace.new(:b)
+    #   ns_c = Namespace.new(:c)
+    #
+    #   # A > B > C
+    #   ns_a << ns_b
+    #   ns_b << ns_c
+    #
+    #   ns_b << Command.new(:foo, :desc => "Foo Desc")
+    #   ns_c << Command.new(:bar, :desc => "Bar Desc")
+    #
+    #   ns_a.commands_and_descriptions
+    #   # => [
+    #   #   ["a:b:foo", "Foo Desc"],
+    #   #   ["a:b:c:bar", "Bar Desc"
+    #   # ]
+    #
+    # Returns an Array of two item Arrays.
     def commands_and_descriptions
       items = []
       @commands.each do |cmd_name, cmd|
         items << [
-          full_name(cmd_name),
+          cmd.full_name,
           cmd.desc
         ]
       end

data/lib/excavator/param.rb

@@ -1,9 +1,23 @@
+# -*- encoding: utf-8 -*-
+
 module Excavator
+
+  # Internal: Param is an object to describe the attributes of a parameter.
+  # There's never a need to instantiate these directly - instead use DSL#param.
   class Param
+
+    # Public: The String/Symbol name of the Param.
     attr_reader :name
+
+    # Public: An optional default value for the Param.
     attr_reader :default
+
+    # Public: An optional String description for the Param.
     attr_reader :desc
-    attr_accessor :short # Set by the ParamParser
+
+    # Public: An optional String (normally one character) to use as the short
+    # switch for the Param.
+    attr_accessor :short
 
     def initialize(name, options = {})
       @name     = name
@@ -13,10 +27,16 @@ module Excavator
       @short    = options[:short]
     end
 
+    # Public: Returns whether or not the Param is required.
+    #
+    # Returns a Boolean.
     def required?
       !optional?
     end
 
+    # Public: Returns whether or not the Param is optional.
+    #
+    # Returns a Boolean.
     def optional?
       @default || (@default.nil? && @optional)
     end

data/lib/excavator/param_parser.rb

@@ -1,9 +1,36 @@
+# -*- encoding: utf-8 -*-
+
 require 'optparse'
 module Excavator
+
+  # Public: ParamParser is a strategy object to integrate Command, Param, and
+  # OptionParser to parse commandline arguments.
+  #
+  # ParamParser is the heart of Excavator. It takes Params and a Command and
+  # creates a command line parser that:
+  #
+  # * automatically assigns short and long switches for params
+  #   (e.g. :name => --name or -n)
+  # * parsers arguments into named parameters
+  # * assigns default values to parameters if specified
+  # * creates a help message
+  # * verifies required params are passed - throws an error if they are not
+  #
+  # Examples
+  #
+  #   parser = Excavator::ParamParser.new
+  #   parser.build(
+  #     :name => "command_name",
+  #     :desc => "command description",
+  #     :params => [ <Param>, <Param>, ... ]
+  #   )
+  #
+  #   parser.parse!(ARGV)
+  #   # => { :param1 => "val", :param2 => "val2", ... }
+  #
   class ParamParser
 
     attr_accessor :name
-    attr_accessor :banner
 
     def initialize
       @parser = OptionParser.new
@@ -11,10 +38,29 @@ module Excavator
       @params = []
     end
 
+    # Public: Builds the parser up with the name, description and Params
+    # passed in.
+    #
+    # This builds an OptionParser object with a "-h" and "--help" option.
+    #
+    # options - A Hash of parameters needed to build the parser.
+    #           :name - A String/Symbol name of the Command.
+    #           :desc - A String description of the command.
+    #           :params - An Array of Params.
+    #
+    # Examples
+    #
+    #   ParamParser.new.build({
+    #     :name => "test_command",
+    #     :desc => "description",
+    #     :params => [<Param>, <Param>]
+    #   })
+    #
+    # Returns nothing.
     def build(options = {})
-      @name   = options[:name] if options[:name]
-      @params = options[:params] if options[:params]
-      @desc   = options[:desc] if options[:desc]
+      @name   = options[:name] #if options[:name]
+      @params = options[:params] #if options[:params]
+      @desc   = options[:desc] #if options[:desc]
 
       required_params = []
       optional_params = []
@@ -26,7 +72,7 @@ module Excavator
         opts = []
 
         # Long option
-        opts << "--#{param.name}"
+        opts << "--#{param.name.to_s.gsub("_", "-")}"
 
         # params require an argument (for now)
         opts << "=#{param.name.to_s.upcase}"
@@ -69,6 +115,36 @@ module Excavator
       end
     end
 
+    # Public: Parses command line arguments. Any argument matching Params are
+    # removed from the argument list (destructive!) and returned in a hash.
+    #
+    # args - An Array of command line arguments. This is usually ARGV.
+    #        If the last argument in the Array is a Hash, it is used as the
+    #        default parameters. This is a convience method to pass arguments
+    #        in a Hash form rather than an Array like ARGV.
+    #
+    # Examples
+    #
+    #   parser = ParamParser.new
+    #   parser.build({...})
+    #
+    #   # Standard usage - assuming there is :name param.
+    #   args = ["command", "--name", "hello"]
+    #   parser.parse!(args)
+    #   # => {:name => "hello"},
+    #   # => args is now ["command"]
+    #
+    #   # Same as above, but the hash is checked to see whether or not
+    #   # the required params are met.
+    #   parser.parse!([{:name => "hello"}])
+    #   # => {:name => "hello"}
+    #
+    #   # Assume :name is required
+    #   parser.parse!(["command"])
+    #   # => Raises MissingParamsError
+    #
+    # Returns a Hash of Symbol names to values.
+    # Raises Excavator::MissingParamsError if args is missing required params.
     def parse!(args)
       @parsed_params = args.last.is_a?(Hash) ? args.pop : {}
 
@@ -79,6 +155,13 @@ module Excavator
       @parsed_params
     end
 
+    # Public: Print out a help message for this parser.
+    def usage
+      @parser.to_s
+    end
+
+    protected
+
     def detect_missing_params!
       missing_params = []
       @params.each do |p|
@@ -90,11 +173,6 @@ module Excavator
       raise MissingParamsError.new(missing_params) if missing_params.size > 0
     end
 
-    def usage
-      @parser.to_s
-    end
-
-    protected
 
     def set_default_params
       @params.each do |param|