mattock 0.2.5 → 0.2.6

data/doc/Specifications

@@ -1,37 +0,0 @@
-
-Mattock::CommandLine
-  should have a name set
-  should produce a command string
-  should succeed
-  should not complain about success
-  Mattock::CommandRunResult
-    should have a result code
-    should have stdout
-
-Mattock::CommandLine that fails
-  should not succeed
-  should raise error if succeed demanded
-
-Mattock::RemoteCommandTask
-  when verification indicates command should proceed
-    should run both commands
-
-Mattock::TemplateHost
-  should be able to do easy templating
-
-Mattock::TaskLib
-  should make root task depend on namespaced
-  should not make namespaced task depend on root task
-  defines
-    should have task :test
-    should have task "test:task"
-    should not have task "random:tasks"
-
-Mattock::Configurable
-  should set defaults
-  should complain about unset required fields
-  should complain about unset nested required fields
-  should not complain when required fields are set
-
-Finished in 0.03167 seconds
-19 examples, 0 failures

data/lib/mattock/cascading-definition.rb

@@ -1,6 +1,25 @@
 require 'mattock/configurable'
 
 module Mattock
+  #Collects shared configuration management behavior for TaskLibs and Tasks
+  #
+  #The chain of events in initialize looks like:
+  #
+  #    setup_defaults
+  #    default_configuration(*tasklibs)
+  #
+  #    yield self if block_given?
+  #
+  #    resolve_configuration
+  #    confirm_configuration
+  #
+  #    define
+  #
+  #Override those methods to adjust how a TaskLib processes its options
+  #
+  #The only method not defined here is {Configurable#setup_defaults}
+  #
+  #For an overview see {TaskLib}
   module CascadingDefinition
     include Configurable
 
@@ -16,16 +35,33 @@ module Mattock
       define
     end
 
+    #@param [TaskLib] tasklibs Other libs upon which this one depends to set
+    #  its defaults
+    #Sets default values for library settings
     def default_configuration(*tasklibs)
     end
 
+    #Called after the configuration block has been called, so secondary
+    #configurations can be set up.  For instance, consider:
+    #
+    #    self.command ||= bin_dir + command_name
+    #
+    #The full path to the command could be set in the configuration block in
+    #the Rakefile, or if bin_dir and command_name are set, we can put those
+    #together.
     def resolve_configuration
     end
 
+    #Last step before definition: confirm that all the configuration settings
+    #have good values.  The default ensures that required settings have been
+    #given values.  Very much shortens the debugging cycle when using TaskLibs
+    #if this is well written.
     def confirm_configuration
       check_required
     end
 
+    #Any useful TaskLib will override this to define tasks, essentially like a
+    #templated Rakefile snippet.
     def define
     end
   end

data/lib/mattock/configurable.rb

@@ -1,4 +1,11 @@
 module Mattock
+  #Handles setting options on objects its mixed into
+  #
+  #Settings can have default values or be required (as opposed to defaulting to
+  #nil).  Settings and their defaults are inherited (and can be overridden) by
+  #subclasses.
+  #
+  #@example (see ClassMethods)
   module Configurable
     RequiredField = Object.new
     class << RequiredField
@@ -12,8 +19,29 @@ module Mattock
     end
     RequiredField.freeze
 
+    #Describes class level DSL & machinery for working with configuration
+    #managment.
+    #
+    #@example Quick example
+    #    class ConfExample
+    #      include Configurable
+    #
+    #      setting :foo
+    #      settings :bar => 1, :baz => 3
+    #      nil_fields :hoo, :ha, :harum
+    #      required_fields :must
+    #
+    #      def initialize
+    #        setup_defaults
+    #      end
+    #    end
+    #
+    #    ce = ConfExample.new
+    #    ce.bar #=> 1
+    #    ce.hoo #=> nil
+    #    ce.hoo = "hallo"
+    #    ce.check_required #=> raises error because :must and :foo aren't set
     module ClassMethods
-
       def default_values
         @default_values ||= {}
       end
@@ -63,12 +91,18 @@ module Mattock
         end
       end
 
+      #Creates an anonymous Configurable - useful in complex setups for nested
+      #settings
+      #@example SSH options
+      #  setting :ssh => nested(:username => "me", :password => nil)
       def nested(hash=nil)
         obj = Class.new(Struct).new
         obj.settings(hash || {})
         return obj
       end
 
+      #Quick list of setting fields with a default value of nil.  Useful
+      #especially with {CascadingDefinition#resolve_configuration}
       def nil_fields(*names)
         names.each do |name|
           setting(name, nil)
@@ -76,6 +110,8 @@ module Mattock
       end
       alias nil_field nil_fields
 
+      #List fields with no default for with a value must be set before
+      #definition.
       def required_fields(*names)
         names.each do |name|
           setting(name)
@@ -83,10 +119,8 @@ module Mattock
       end
       alias required_field required_fields
 
-      # @macro [attack] configurable_property
-      #   @method $1
-      #   @return [$2] The default value of $1
-      #   @method $1=
+      #Defines a setting on this class - much like a attr_accessible call, but
+      #allows for defaults and required settings
       def setting(name, default_value = RequiredField)
         name = name.to_sym
         attr_accessor(name)
@@ -96,6 +130,8 @@ module Mattock
         default_values[name] = default_value
       end
 
+      #@param [Hash] hash Pairs of name/value to be converted into
+      #  setting/default
       def settings(hash)
         hash.each_pair do |name, value|
           setting(name, value)
@@ -107,6 +143,7 @@ module Mattock
         mod.extend ClassMethods
       end
     end
+
     extend ClassMethods
 
     def copy_settings_to(other)
@@ -114,11 +151,15 @@ module Mattock
       self
     end
 
+    #Call during initialize to set default values on settings - if you're using
+    #Configurable outside of Mattock, be sure this gets called.
     def setup_defaults
       self.class.set_defaults_on(self)
       self
     end
 
+    #Checks that all required fields have be set, otherwise raises an error
+    #@raise RuntimeError if any required fields are unset
     def check_required
       missing = self.class.missing_required_fields_on(self)
       unless missing.empty?

data/lib/mattock/tasklib.rb

@@ -2,10 +2,47 @@ require 'rake/tasklib'
 require 'mattock/cascading-definition'
 
 module Mattock
+  #Rake::Tasklib provides a common, well known way to generalize tasks and use
+  #them in multiple projects.  The way it's used in a Rakefile is something
+  #like:
+  #
+  #    CoolTask.new(:args) do |t|
+  #      t.option_one = "cool"
+  #      t.option_two = "very"
+  #    end
+  #
+  #Typically, the #initialize method for CoolTask yields itself into the block
+  #(so, 't' in the example) and then runs #define which does the heavy lifting
+  #to actually create tasks and set them up with dependencies and whatnot.
+  #
+  #Rake::Tasklib doesn't really provide much in the way of help or guidance
+  #about how to do this, though, and everyone winds up having to do a lot of
+  #the same work.
+  #
+  #Mattock::TaskLib provides a base class to build tasklibs on so that you can
+  #get to what you care about, and get option validation as well.
+  #
+  #The convention that's added in Mattock is that Tasklibs are passed to each
+  #other as arguments, so that behavior can be composed out of modular
+  #components, a la:
+  #
+  #    transport = HTTPTasks.new do |t|
+  #      t.server = http://mycoolserver.com
+  #    end
+  #
+  #    UploadTasks.new(transport) do |t|
+  #      t.dir = "./source_dir"
+  #    end
+  #
+  #The configuration handling is provided by {CascadingDefinition}, and
+  #configuration options are built using {Configurable}
   class TaskLib < Rake::TaskLib
     include CascadingDefinition
 
     attr_writer :namespace_name
+
+    #The namespace this lib's tasks will created within.  Changeable at
+    #instatiation
     def self.default_namespace(name)
       setting(:namespace_name, name)
     end
@@ -17,12 +54,18 @@ module Mattock
       super
     end
 
+    #Records tasks as they are created
     def task(*args)
       a_task = super
       @tasks << a_task
       return a_task
     end
 
+    #@overload in_namespace(args)
+    #  maps the arguments to namespace-prefixed names, for use in Rake
+    #  dependency declaration
+    #@overload in_namespace &block
+    #  wraps the block in a Rake namespace call
     def in_namespace(*tasknames)
       if tasknames.empty?
         if block_given?
@@ -49,9 +92,12 @@ module Mattock
       nil
     end
 
+    #Wraps a single task in lib's namespace
     def [](taskname)
       in_namespace(taskname).first
     end
   end
-  Tasklib = TaskLib #Because I can never remember
+
+  #Because I can never remember
+  Tasklib = TaskLib
 end

data/lib/mattock/yard_extensions.rb

@@ -17,8 +17,18 @@ module Mattock
         end
       end
 
+      def root
+        ns = namespace
+        until ns.root?
+          ns = ns.namespace
+        end
+        ns
+      end
+
       def process
         return unless mattock_defining?(namespace, statement[0][0])
+        (root[:tasklibs] ||= []) << namespace
+        p __LINE__ => [root, root[:tasklibs]]
         namespace[:task_definition] = statement[2]
       end
     end

metadata

@@ -2,7 +2,7 @@
 name: mattock
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors: 
 - Judson Lester
@@ -57,113 +57,8 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- doc/js/full_list.js
-- doc/js/app.js
-- doc/js/jquery.js
-- doc/css/style.css
-- doc/css/full_list.css
-- doc/css/common.css
-- doc/Mattock.html
-- doc/RSpecTest.html
-- doc/Ungemmer.html
-- doc/FileSandbox/SandboxFile.html
-- doc/FileSandbox/HaveContents.html
-- doc/FileSandbox/Sandbox.html
-- doc/file_list.html
 - doc/README
 - doc/Specifications
-- doc/index.html
-- doc/class_list.html
-- doc/top-level-namespace.html
-- doc/FileSandbox.html
-- doc/coverage/index.html
-- doc/coverage/assets/0.5.3/highlight.css
-- doc/coverage/assets/0.5.3/favicon_yellow.png
-- doc/coverage/assets/0.5.3/jquery.dataTables.min.js
-- doc/coverage/assets/0.5.3/stylesheet.css
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_sw.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_e.png
-- doc/coverage/assets/0.5.3/fancybox/blank.gif
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_n.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_s.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_w.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_title_over.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_close.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_loading.png
-- doc/coverage/assets/0.5.3/fancybox/jquery.fancybox-1.3.1.pack.js
-- doc/coverage/assets/0.5.3/fancybox/fancybox-x.png
-- doc/coverage/assets/0.5.3/fancybox/fancybox-y.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_nav_right.png
-- doc/coverage/assets/0.5.3/fancybox/fancybox.png
-- doc/coverage/assets/0.5.3/fancybox/jquery.fancybox-1.3.1.css
-- doc/coverage/assets/0.5.3/fancybox/fancy_title_right.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_title_left.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_ne.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_title_main.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_nw.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_nav_left.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_se.png
-- doc/coverage/assets/0.5.3/favicon_green.png
-- doc/coverage/assets/0.5.3/magnify.png
-- doc/coverage/assets/0.5.3/smoothness/jquery-ui-1.8.4.custom.css
-- doc/coverage/assets/0.5.3/smoothness/images/ui-icons_888888_256x240.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_glass_55_fbf9ee_1x400.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_flat_75_ffffff_40x100.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_glass_75_e6e6e6_1x400.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-icons_2e83ff_256x240.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-icons_454545_256x240.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-icons_cd0a0a_256x240.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-icons_222222_256x240.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_glass_75_dadada_1x400.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_flat_0_aaaaaa_40x100.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_highlight-soft_75_cccccc_1x100.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_glass_65_ffffff_1x400.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_glass_95_fef1ec_1x400.png
-- doc/coverage/assets/0.5.3/jquery.url.js
-- doc/coverage/assets/0.5.3/app.js
-- doc/coverage/assets/0.5.3/favicon_red.png
-- doc/coverage/assets/0.5.3/highlight.pack.js
-- doc/coverage/assets/0.5.3/jquery.timeago.js
-- doc/coverage/assets/0.5.3/loading.gif
-- doc/coverage/assets/0.5.3/jquery-1.6.2.min.js
-- doc/Mattock/TaskMixin/ClassMethods.html
-- doc/Mattock/WrappingChain.html
-- doc/Mattock/YARDExtensions.html
-- doc/Mattock/CommandLine.html
-- doc/Mattock/RemoteCommandTask.html
-- doc/Mattock/CascadingDefinition.html
-- doc/Mattock/Configurable.html
-- doc/Mattock/PipelineChain.html
-- doc/Mattock/FileCreationTask.html
-- doc/Mattock/TaskLib.html
-- doc/Mattock/RakeExampleGroup/TaskManager.html
-- doc/Mattock/RakeExampleGroup/Matchers.html
-- doc/Mattock/RakeExampleGroup.html
-- doc/Mattock/CommandRunResult.html
-- doc/Mattock/TemplateHost.html
-- doc/Mattock/YARDExtensions/NilFieldsHandler.html
-- doc/Mattock/YARDExtensions/SettingsHandler.html
-- doc/Mattock/YARDExtensions/DefineHandler.html
-- doc/Mattock/YARDExtensions/SettingHandler.html
-- doc/Mattock/YARDExtensions/RequiredFieldsHandler.html
-- doc/Mattock/PrereqChain.html
-- doc/Mattock/CommandLineExampleGroup/Matchers.html
-- doc/Mattock/CommandChain.html
-- doc/Mattock/CommandTask.html
-- doc/Mattock/MultiTask.html
-- doc/Mattock/Configurable/ClassMethods.html
-- doc/Mattock/Configurable/Struct.html
-- doc/Mattock/ValiseManager.html
-- doc/Mattock/MockCommandResult.html
-- doc/Mattock/TaskMixin.html
-- doc/Mattock/ShellEscaped.html
-- doc/Mattock/Task.html
-- doc/Mattock/CommandLineExampleGroup.html
-- doc/Mattock/FileTask.html
-- doc/_index.html
-- doc/file.README.html
-- doc/method_list.html
-- doc/frames.html
 files: 
 - yard_templates/default/module/setup.rb
 - yard_templates/default/module/html/setting_summary.erb
@@ -192,111 +87,6 @@ files:
 - spec/template-host.rb
 - spec_help/spec_helper.rb
 - spec_help/gem_test_suite.rb
-- doc/js/full_list.js
-- doc/js/app.js
-- doc/js/jquery.js
-- doc/css/style.css
-- doc/css/full_list.css
-- doc/css/common.css
-- doc/Mattock.html
-- doc/RSpecTest.html
-- doc/Ungemmer.html
-- doc/FileSandbox/SandboxFile.html
-- doc/FileSandbox/HaveContents.html
-- doc/FileSandbox/Sandbox.html
-- doc/file_list.html
-- doc/index.html
-- doc/class_list.html
-- doc/top-level-namespace.html
-- doc/FileSandbox.html
-- doc/coverage/index.html
-- doc/coverage/assets/0.5.3/highlight.css
-- doc/coverage/assets/0.5.3/favicon_yellow.png
-- doc/coverage/assets/0.5.3/jquery.dataTables.min.js
-- doc/coverage/assets/0.5.3/stylesheet.css
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_sw.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_e.png
-- doc/coverage/assets/0.5.3/fancybox/blank.gif
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_n.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_s.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_w.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_title_over.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_close.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_loading.png
-- doc/coverage/assets/0.5.3/fancybox/jquery.fancybox-1.3.1.pack.js
-- doc/coverage/assets/0.5.3/fancybox/fancybox-x.png
-- doc/coverage/assets/0.5.3/fancybox/fancybox-y.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_nav_right.png
-- doc/coverage/assets/0.5.3/fancybox/fancybox.png
-- doc/coverage/assets/0.5.3/fancybox/jquery.fancybox-1.3.1.css
-- doc/coverage/assets/0.5.3/fancybox/fancy_title_right.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_title_left.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_ne.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_title_main.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_nw.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_nav_left.png
-- doc/coverage/assets/0.5.3/fancybox/fancy_shadow_se.png
-- doc/coverage/assets/0.5.3/favicon_green.png
-- doc/coverage/assets/0.5.3/magnify.png
-- doc/coverage/assets/0.5.3/smoothness/jquery-ui-1.8.4.custom.css
-- doc/coverage/assets/0.5.3/smoothness/images/ui-icons_888888_256x240.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_glass_55_fbf9ee_1x400.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_flat_75_ffffff_40x100.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_glass_75_e6e6e6_1x400.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-icons_2e83ff_256x240.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-icons_454545_256x240.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-icons_cd0a0a_256x240.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-icons_222222_256x240.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_glass_75_dadada_1x400.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_flat_0_aaaaaa_40x100.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_highlight-soft_75_cccccc_1x100.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_glass_65_ffffff_1x400.png
-- doc/coverage/assets/0.5.3/smoothness/images/ui-bg_glass_95_fef1ec_1x400.png
-- doc/coverage/assets/0.5.3/jquery.url.js
-- doc/coverage/assets/0.5.3/app.js
-- doc/coverage/assets/0.5.3/favicon_red.png
-- doc/coverage/assets/0.5.3/highlight.pack.js
-- doc/coverage/assets/0.5.3/jquery.timeago.js
-- doc/coverage/assets/0.5.3/loading.gif
-- doc/coverage/assets/0.5.3/jquery-1.6.2.min.js
-- doc/Mattock/TaskMixin/ClassMethods.html
-- doc/Mattock/WrappingChain.html
-- doc/Mattock/YARDExtensions.html
-- doc/Mattock/CommandLine.html
-- doc/Mattock/RemoteCommandTask.html
-- doc/Mattock/CascadingDefinition.html
-- doc/Mattock/Configurable.html
-- doc/Mattock/PipelineChain.html
-- doc/Mattock/FileCreationTask.html
-- doc/Mattock/TaskLib.html
-- doc/Mattock/RakeExampleGroup/TaskManager.html
-- doc/Mattock/RakeExampleGroup/Matchers.html
-- doc/Mattock/RakeExampleGroup.html
-- doc/Mattock/CommandRunResult.html
-- doc/Mattock/TemplateHost.html
-- doc/Mattock/YARDExtensions/NilFieldsHandler.html
-- doc/Mattock/YARDExtensions/SettingsHandler.html
-- doc/Mattock/YARDExtensions/DefineHandler.html
-- doc/Mattock/YARDExtensions/SettingHandler.html
-- doc/Mattock/YARDExtensions/RequiredFieldsHandler.html
-- doc/Mattock/PrereqChain.html
-- doc/Mattock/CommandLineExampleGroup/Matchers.html
-- doc/Mattock/CommandChain.html
-- doc/Mattock/CommandTask.html
-- doc/Mattock/MultiTask.html
-- doc/Mattock/Configurable/ClassMethods.html
-- doc/Mattock/Configurable/Struct.html
-- doc/Mattock/ValiseManager.html
-- doc/Mattock/MockCommandResult.html
-- doc/Mattock/TaskMixin.html
-- doc/Mattock/ShellEscaped.html
-- doc/Mattock/Task.html
-- doc/Mattock/CommandLineExampleGroup.html
-- doc/Mattock/FileTask.html
-- doc/_index.html
-- doc/file.README.html
-- doc/method_list.html
-- doc/frames.html
 homepage: http://mattock.rubyforge.org/
 licenses: 
 - MIT
@@ -306,7 +96,7 @@ rdoc_options:
 - --main
 - doc/README
 - --title
-- mattock-0.2.5 RDoc
+- mattock-0.2.6 RDoc
 require_paths: 
 - lib/
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -314,7 +104,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -48882383
+      hash: 536497039
       segments: 
       - 0
       version: "0"