excavator 0.0.1 → 0.0.2

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2012 Peter Bui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,280 @@
+# Excavator
+
+Excavator is a commandline scripting framework. It takes care of parameter
+parsing, command namespacing and command loading so that you can focus on
+writing your scripts.
+
+Excavator is like a stripped down version of rake but uses optparse for
+parameter parsing.
+
+Here's a simple, albeit contrived, example of what you can do with Excavator.
+
+    require 'excavator'
+
+    param :name
+    command :hello do
+      puts "Hello, #{params[:name]}!"
+    end
+
+    Excavator.run(ARGV)
+
+Place the previous contents in a file named `say` and then run it:
+
+    $ chmod a+x say
+    $ say hello --name paydro
+    Hello, paydro!
+    $
+
+
+# Installation
+
+    gem install excavator
+
+# Usage
+
+Excavator does not come with a commandline tool. The way to use Excavator is to first create an executable file, then add commands in the file.
+
+Creating the file:
+
+    $ touch my_commands
+    $ chmod a+x my_commands
+
+Edit `my_commands` and add the following:
+
+    #!/usr/bin/env ruby
+    require 'excavator'
+
+    namespace :happy_quotes do
+      commands :smile do
+        # ...
+      end
+    end
+
+    namespace :jokes do
+      commands :knock_knock do
+        # ...
+      end
+    end
+
+    Excavator.run(ARGV) # This runs it
+
+Now you can execute the commands.
+
+    $ my_commands jokes:knock_knock
+    ...
+    $ my_commands happy_quotes:smile
+    ...
+    $
+
+When the commands pile up, you can move them to other files and tell Excavator where all your commands live.
+
+For instance, let's assume we have the same `my_commands` script above, but we also add the directory `commands/`. In `commands/`, we refactor the previous commands from `my_commands`. The file hiearchy now looks like this:
+
+    /Users/paydro/
+      commands/
+        happy_quotes.rb
+        jokes.rb
+      my_commands # The original file
+
+Now, inside `my_commands`, all we have is this:
+
+    #!/usr/bin/env ruby
+    require 'excavator'
+    Excavator.command_paths = ["/Users/paydro/commands"]
+    Excavator.run(ARGV)
+
+By default, Excavator already looks into the `commands/` if it exists next to
+the script, but it's shown above for completeness.
+
+## Commands
+
+Commands are created with the `command` method.
+
+    command :list do
+      # ...
+    end
+
+    command :another do
+      # ...
+    end
+
+### Call Other Commands
+
+Use `execute` to call other commands from within a command.
+
+    command :print do
+      execute :my_name
+    end
+
+    command :my_name do
+      puts "paydro"
+    end
+
+You can even pass parameters to other commands with a hash.
+
+    # Prints "paydro"
+    command :print do
+      execute :my_name, :name => "paydro"
+    end
+
+    param :name
+    command :my_name do
+      puts params[:name]
+    end
+
+
+## Command Description
+
+Describe your command using the `desc` method above the command definition.
+
+    desc "Prints all the servers in the cluster"
+    command :list_servers do
+      # ...
+    end
+
+## Namespaces
+
+Group similar or related commands via `namespace`.
+
+    # Creates the following commands:
+    # - servers:list
+    # - servers:create
+    # - servers:boot:with_ruby
+
+    namespace :servers do
+      command :list do
+        # ...
+      end
+
+      command :create do
+        # ...
+      end
+
+      namespace :boot do
+        command :with_ruby do
+          # ...
+        end
+      end
+    end
+
+## Parameters
+
+Parameters are available within the command body via the `params`.
+
+    param :first_name
+    param :last_name
+    command :print do
+      puts params[:first_name]
+      puts params[:last_name]
+    end
+
+### Required, Optional, Defaults
+
+Params are required by default. To make them optional, specify the optional flag or specify a default
+
+    # Required - if not passed, will stop the script
+    param :first_name
+
+    # Optional
+    param :last_name, :optional => true
+
+    # Optional - has a default
+    param :country, :default => "USA"
+    command :print do
+      puts params[:first_name]
+      puts params[:last_name] # Might be nil!
+      puts params[:country] # USA unless something was passed
+    end
+
+### Description
+
+Params can take descriptions so that the script can print them out with `-h`.
+
+    param :last_name, :desc => "Your last name"
+
+
+### Long and Short Switches
+
+Parameters are assigned long and short switches unless they are specified. The
+short switch is usually the first character in the name of the param. If there
+are duplicates, then the param parser will continue to move to the next
+character in the name until it finds a unique character. If it cannot find a
+unique character, then the parameter will not have a short switch.
+
+    # --abc, -a
+    param :abc
+
+    # --bc, -b
+    param :bc
+
+    # --ab
+    # "a" and "b" are already taken above, so this one doesn't have a short
+    # switch
+    param :ab
+
+    # Force a short switch, -c
+    param :aabb, :short => "c"
+
+## Help Commands
+
+You can list all commands you've created by calling your script with `--help`, `-h`, or `-?`. This will print out all the commands and their descriptions for you.
+
+    # Lists all commands (assuming our commands are in "servers")
+    $ servers --help
+    ... prints out commands ...
+    $
+
+To view the usage of a single command, pass the `-h` or `--help` switch when
+calling the command.
+
+    # Lists usage of "list" (assuming our commands are in "servers")
+    $ servers list -h
+    ... usage ...
+    $
+
+
+# Add Helpers For Commands
+
+Commands run within and instance of `Excavator::Environment`, and it has a few methods that you can use. To extend this, you can use `Excavator::Environment#modify`. This is really just a helper give you access to the `Excavator::Environment` scope (i.e., for including other modules).
+
+    require 'excavator'
+
+    module Helpers
+      def hello
+        puts "hello!"
+      end
+    end
+
+    module ExpensiveHTTPCalls
+      # ...
+    end
+
+    Excavator.environment_class.modify Helpers, ExpensiveHTTPCalls
+
+    # OR
+
+    Excavator.environment_class.modify do
+      include Helpers
+    end
+
+    command :example do
+      hello
+    end
+
+# Contrib
+
+## Bugs
+
+Submit bugs [on GitHub](https://github.com/paydro/excavator/issues).
+
+## Hacking
+
+Please fork the [repository](https://github.com/paydro/excavator) on GitHub and send me a pull request. Here's a few guidelines:
+
+* Use 80 character columns
+* Write tests!
+* Follow other examples in the code
+
+# Credits
+
+[Peter Bui](peter@paydrotalks.com)

data/lib/excavator.rb

@@ -1,5 +1,9 @@
+# -*- encoding: utf-8 -*-
+
 require 'pathname'
 
+# Excavator automatically creates a command line parser for your params as well
+# as building a simple usage and option messages for your scripts.
 module Excavator
   class ExcavatorError < ::StandardError; end
 
@@ -11,37 +15,44 @@ module Excavator
     end
   end
 
-  def self.config(name, default)
-    @config   ||= {}
-    @defaults ||= {}
-    @defaults[name.to_sym] = default
-    module_eval <<-MOD, __FILE__, __LINE__  + 1
-      def self.#{name}
-        @config[:#{name}] || @defaults[:#{name}]
-      end
-
-      def self.#{name}=(val)
-        @config[:#{name}] = val
-      end
-    MOD
-  end
-
+  # Public: The current working directory for the Excavator script.
+  #
+  # Returns a Pathname.
   def self.cwd
     @cwd ||= Pathname.new(Dir.pwd).expand_path
   end
 
-  def self.reset!
-    self.runner = nil
-  end
 
+  # Public: The global Runner object. This object is called from
+  # Excavator.run to start the whole command loading, commandline parsing and
+  # command execution process.
+  #
+  # Returns a Runner class.
   def self.runner
     @runner ||= runner_class.new
   end
 
+  # Public: The global Runner assignment method.
+  #
+  # runner - Any Class that implements Excavator::Runner's public api.
+  #
   def self.runner=(runner)
     @runner = runner
   end
 
+  # Public: Start Excavator.
+  #
+  # On command error, this method will exit with a status of 1 and print
+  # the error message to $stderr.
+  #
+  # params - An Array of parameters. This is normally ARGV.
+  #
+  # Examples
+  #
+  #   Excavator.run(ARGV)
+  #   # => executes command passed in via ARGV
+  #
+  # Returns the object returned to by the command or exits with a status of 1.
   def self.run(params)
     begin
       runner.run(params)
@@ -56,6 +67,48 @@ module Excavator
     end
   end
 
+  # Internal: Setup class level configuration variables with defaults.
+  #
+  # Examples
+  #
+  #   module Excavator
+  #     config :test, "test"
+  #   end
+  #
+  #   Excavator.test
+  #   # => "test"
+  #
+  #   Excavator.test = "123"
+  #   Excavator.test
+  #   # => "123"
+  #
+  # Returns nothing.
+  def self.config(name, default)
+    @config   ||= {}
+    @defaults ||= {}
+    @defaults[name.to_sym] = default
+    module_eval <<-MOD, __FILE__, __LINE__  + 1
+      def self.#{name}
+        @config[:#{name}] || @defaults[:#{name}]
+      end
+
+      def self.#{name}=(val)
+        @config[:#{name}] = val
+      end
+    MOD
+  end
+
+  # Internal: Resets the global Runner object. This is primarily used in
+  # testing.
+  #
+  # Examples
+  #
+  #   Excavator.reset!
+  #
+  # Returns nothing.
+  def self.reset!
+    self.runner = nil
+  end
 end
 
 require 'excavator/version'
@@ -69,7 +122,6 @@ require 'excavator/runner'
 require 'excavator/table_view'
 
 module Excavator
-  # Setup defaults classes
   config :command_paths,      []
   config :runner_class,       Runner
   config :namespace_class,    Namespace

data/lib/excavator/command.rb

@@ -1,24 +1,37 @@
-require 'timeout'
+# -*- encoding: utf-8 -*-
+
 module Excavator
+
+  # Public: A Command is building block in Excavator. Commands are built
+  # incrementally (normally via methods in Excavator::DSL).
   class Command
     # Descriptors
     attr_accessor :name, :desc, :namespace
 
-    # Block to run when command is executed
+    # The logic for the command
     attr_accessor :block
 
     # A list of Param objects
     attr_reader :param_definitions
 
+    # Public: Parsed params (parsed using ParamParser)
     attr_reader :params
+
+    # Public: An Array copy of arguments passed into this command
+    # (i.e, before ParamParser#parse! is called)
     attr_reader :raw_params
+
+    # Public: An Array of unparsed parameters. These are the left over arguments
+    # after ParamParser#parse! is called.
     attr_reader :unparsed_params
 
+    # Public: Reference to the Runner
     attr_reader :runner
 
     def initialize(runner, options = {})
       @runner            = runner
       @name              = options[:name]
+      @desc              = options[:desc]
       @block             = options[:block]
       @param_definitions = options[:param_definitions] || []
       @namespace         = options[:namespace]
@@ -27,21 +40,61 @@ module Excavator
       @params            = {}
     end
 
+    # Public: Add a Param to this command.
+    #
+    # Examples
+    #
+    #   command = Command.new
+    #   command.add_param(Param.new(:test))
+    #
+    # Returns nothing.
     def add_param(param)
       self.param_definitions << param
     end
 
-    def execute(*inputs)
-      inputs.flatten!
-      parse_params inputs
+    # Public: Execute the Command's block within a Excavator::Environment
+    # instance. Arguments are parsed, setup with default values, and checked
+    # to ensure the Command has all the proper parameters.
+    #
+    # args - An Array of arguments to pass into the block. This is normally
+    #        the same format as ARGV.
+    #
+    # Examples
+    #
+    #   command = Command.new( ... )
+    #   command.execute(["-a", "abc", "--foo", "bar"])
+    #
+    # Returns the value returned by the Command's block.
+    def execute(*args)
+      args.flatten!
+      parse_params args
       run
     end
 
+    # Public: Execute this command. This is like #execute except the parameters
+    # is a Hash.
+    #
+    # parsed_params - A Hash of params to pass into the Command's block.
+    #
+    # Examples
+    #
+    #   command = Command.new( ... )
+    #   command.execute({:a => "abc", :foo => "bar})
+    #
+    # Returns the value returned by the Command's block.
     def execute_with_params(parsed_params = {})
       parse_params [parsed_params]
       run
     end
 
+    # Public: The full name of the Command. This includes the Namespace's name
+    # and the Namespace's ancestor's names.
+    #
+    # Returns a String.
+    def full_name
+      namespace.nil? ? name.to_s : namespace.full_name(name)
+    end
+
     protected
 
     # Internal
@@ -65,11 +118,8 @@ module Excavator
 
     def build_parser
       return if @parser_built
-      command_name = ""
-      command_name << "#{namespace.full_name}:" if namespace
-      command_name << name.to_s
       @param_parser.build(
-        :name   => command_name,
+        :name   => full_name,
         :desc   => desc,
         :params => param_definitions
       )