excavator 0.0.1 → 0.0.2

data/lib/excavator/runner.rb

@@ -1,10 +1,26 @@
+# -*- encoding: utf-8 -*-
+
 require 'excavator'
+
 module Excavator
+
+  # Public: Runner is the entry point into an Excavator script library. When
+  # running an Excavator script from the command line, a Runner object is
+  # created.
+  #
+  # Runner duties:
+  #
+  # * Load all Excavator commands.
+  # * Provides the object that Excavator::DSL manipulates.
+  # * Finds the command from the command line arguments and executes.
+  # * Creates a useful help message to list all commands defined in the library.
+  #
   class Runner
 
-    # Runner specific vars
-    attr_accessor :command_paths
-    attr_accessor :commands
+    # Public: An Array of filesystem paths where Excavator commands are found.
+    attr_writer :command_paths
+
+    # Public: A pointer to the current namespace.
     attr_reader :current_namespace
 
     def initialize
@@ -12,35 +28,57 @@ module Excavator
       @current_namespace = @namespace
     end
 
+    # Public: Return the current working directory for the script.
     def cwd
       Excavator.cwd
     end
 
-    def namespaces
-      @namespaces
-    end
-
-    def namespace
-      @namespace
-    end
-
+    # Public: A pointer to the current namespace being worked on.
     def current_namespace
       @current_namespace
     end
 
+    # Public: An Array of filesystem paths where Excavator commands are found.
+    # Defaults to the current directory's "command/" directory.
+    def command_paths
+      @command_paths = Excavator.command_paths || [cwd.join("commands")]
+    end
+
+    # Public: A helper to move the current_namespace pointer to new namespace,
+    # yield, and then return the pointer back to the previous namespace. If the
+    # namespace argument already exists (e.g., created by another file), then
+    # this points to the previously created namespace.
+    #
+    # name - A String/Symbol of the namespace to move the current_namespace
+    #        pointer to.
+    #
+    # Examples
+    #
+    #   runner = Runner.new
+    #   runner.in_namespace("test") do
+    #     runner.current_namespace
+    #     # => <Namespace "test">
+    #   end
+    #
+    # Returns nothing.
     def in_namespace(name)
-      ns = @current_namespace.namespace(name)
-      ns = @current_namespace << Excavator.namespace_class.new(name) unless ns
+      ns = @current_namespace.namespace(name) ||
+           Excavator.namespace_class.new(name)
+      @current_namespace << ns
+
       @current_namespace = ns
       yield
       @current_namespace = ns.parent
     end
 
-    def clear_commands!
-      self.commands = {}
-    end
-
-    def run(*args)
+    # Public: The entry point into all commands. This will load all commands
+    # from any external Excavator files, find the command from the command line,
+    # and execute the command.
+    #
+    # This method is never called directly. See Excavator.run.
+    #
+    # Returns value returned from the Command.
+    def run(args = ARGV)
       args.flatten!
 
       name = args.delete_at(0)
@@ -55,6 +93,12 @@ module Excavator
       command.execute *args
     end
 
+    # Public: Find a command given it's full name.
+    #
+    # cmd - A String/Symbol full name of the Command to look up.
+    #       (e.g., "server:test:integration")
+    #
+    # Returns a Command.
     def find_command(cmd)
       *namespaces, command_name = cmd.to_s.split(':').collect {|c| c.to_sym }
       cur_namespace = current_namespace
@@ -65,10 +109,21 @@ module Excavator
       cur_namespace.command(command_name)
     end
 
-    def display_help?(command_name)
-      ["-h", "-?", "--help", "help"].include?(command_name)
+    # Public: The last command being worked on. This is designed for use
+    # with Excavator::DSL methods.
+    def last_command
+      @last_command ||= Excavator.command_class.new(
+        self, :namespace => current_namespace
+      )
     end
 
+    # Public: Clear the last command being worked on. This is designed for use
+    # with Excavator::DSL methods.
+    def clear_last_command!
+      @last_command = nil
+    end
+
+    # Internal: Display the list of all command names and their descriptions.
     def display_help
       table_view = Excavator::TableView.new do |t|
         t.title "#{File.basename($0)} commands:\n"
@@ -84,24 +139,23 @@ module Excavator
       puts table_view
     end
 
-    def load_commands
-      command_paths.each do |path|
-        Dir["#{path.to_s}/**/*.rb"].each { |file| load file }
-      end
+    # Internal: The root namespace for all other commands and namespaces.
+    def namespace
+      @namespace
     end
 
-    def last_command
-      @last_command ||= Excavator.command_class.new(
-        self, :namespace => current_namespace
-      )
-    end
+    protected
 
-    def clear_last_command!
-      @last_command = nil
+    def display_help?(command_name)
+      ["-h", "-?", "--help", "help"].include?(command_name)
     end
 
-    def command_paths
-      @command_paths = Excavator.command_paths || [cwd.join("commands")]
+    # Internal: Loop through each command path and load all *.rb files.
+    def load_commands
+      command_paths.each do |path|
+        Dir["#{path.to_s}/**/*.rb"].each { |file| load file }
+      end
     end
+
   end # Runner
 end

data/lib/excavator/table_view.rb

@@ -1,3 +1,5 @@
+# -*- encoding: utf-8 -*-
+
 require 'excavator'
 module Excavator
   class TableView

data/lib/excavator/version.rb

@@ -1,3 +1,5 @@
+# -*- encoding: utf-8 -*-
+
 module Excavator
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/test/test_helper.rb

@@ -1,3 +1,5 @@
+# -*- encoding: utf-8 -*-
+
 require 'pathname'
 basedir = Pathname.new(File.dirname(__FILE__)).join("..").expand_path
 $LOAD_PATH.unshift(basedir.join("lib").to_s)

data/test/unit/command_test.rb

@@ -71,5 +71,26 @@ context "Command" do
     end
     assert error.params.include?(:server)
   end
+
+  test "#full_name includes namespace" do
+    ns = Namespace.new(:this_is_not_used_in_full_name)
+    ns1 = Namespace.new(:servers)
+    ns << ns1
+    cmd = Command.new(Excavator.runner)
+    cmd.name = :create
+    cmd.namespace = ns1
+
+    assert_equal "servers:create", cmd.full_name
+  end
+
+  test "#full_name does not include namespace if namespace's parent is nil" do
+    cmd = Command.new(Excavator.runner)
+    cmd.name = :create
+    cmd.namespace = Namespace.new(:servers)
+
+    assert cmd.namespace.parent.nil?
+    assert_equal "create", cmd.full_name
+  end
+
 end # Command
 

data/test/unit/namespace_test.rb

@@ -4,6 +4,7 @@ context "Namespace" do
   include Excavator
 
   setup do
+    Excavator.reset!
     @namespace = Namespace.new
   end
 
@@ -39,17 +40,23 @@ context "Namespace" do
   end
 
   test "#commands_and_descriptions returns names and description" do
-    cmd = MiniTest::Mock.new
-    cmd.expect(:name, "command")
-    cmd.expect(:desc, "command description")
+    cmd = Command.new(
+      Excavator.runner,
+      :name => "command",
+      :desc => "command description",
+      :namespace => @namespace
+    )
     @namespace << cmd
 
     ns1 = Namespace.new("first")
     @namespace << ns1
 
-    inner_cmd = MiniTest::Mock.new
-    inner_cmd.expect(:name, "inner_command")
-    inner_cmd.expect(:desc, "inner command description")
+    inner_cmd = Command.new(
+      Excavator.runner,
+      :name => "inner_command",
+      :desc => "inner command description",
+      :namespace => ns1
+    )
     ns1 << inner_cmd
 
     expected = [

data/test/unit/param_parser_test.rb

@@ -94,7 +94,7 @@ test description
 USAGE: test-command [options]
 
 REQUIRED:
-    -s, --server_id=SERVER_ID        Server instance id
+    -s, --server-id=SERVER_ID        Server instance id
 
 OPTIONAL:
     -r, --region=REGION              A region to use

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: excavator
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-06 00:00:00.000000000Z
+date: 2012-02-08 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &70321668148280 !ruby/object:Gem::Requirement
+  requirement: &70295484482360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 2.10.0
   type: :development
   prerelease: false
-  version_requirements: *70321668148280
+  version_requirements: *70295484482360
 - !ruby/object:Gem::Dependency
   name: ruby-debug19
-  requirement: &70321668147020 !ruby/object:Gem::Requirement
+  requirement: &70295484481400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70321668147020
+  version_requirements: *70295484481400
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70321668145740 !ruby/object:Gem::Requirement
+  requirement: &70295484480420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70321668145740
+  version_requirements: *70295484480420
 description: ! 'Excavator is a scripting framework for writing multi-command executables
   for the
 
@@ -52,15 +52,15 @@ description: ! 'Excavator is a scripting framework for writing multi-command exe
 '
 email:
 - peter@paydrotalks.com
-executables:
-- excavator
+executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
+- LICENSE
+- README.md
 - Rakefile
-- bin/excavator
 - excavator.gemspec
 - lib/excavator.rb
 - lib/excavator/command.rb

data/bin/excavator

@@ -1,3 +0,0 @@
-#!/usr/bin/env ruby
-require 'excavator'
-Excavator.run(ARGV)