mattock 0.2.12 → 0.2.13

data/doc/README

@@ -1,2 +1,53 @@
-== This is a Really Cool Ruby Thing
-=== ( That deserves better documentation than this. )
+== Mattock
+=== A powerful companion to Rake
+
+The goal for Mattock is to be able to build configurable, composable tasklibs
+for Rake quickly, and get validation that they're working properly.
+
+Throughout, the goal has been to lean hard on straight up Ruby, with as little
+metaprogrammitic DSL nonsense as I could get away with.
+
+In fact, basically the only DSL stuff in Mattock are settings for Tasklibs.
+The gory details are in {Mattock::Configurable}.  Inheritable, defaultable,
+verifying, copyable settings.  Nothing you haven't seen done before.
+
+=== Tasklibs
+
+The upshot of Mattock is being able to build Rake Tasklibs so that you can do
+things like:
+
+  tk = Toolkit.new do |tk|
+    tk.file_lists.project = [__FILE__]
+  end
+
+  tk.in_namespace do
+    vc = Git.new(tk) do
+      |vc| vc.branch = "master"
+    end
+    task tk.finished_files.build => vc["is_checked_in"]
+  end
+
+Things of note there: the "Git" tasklib takes the Toolkit tasklib as an
+argument.  Git can pull out settings from Toolkit.  (Conversely, that means as
+these tasklibs are designed, common settings can be pulled up into parent
+tasklibs.)  Libs with related concerns can get hooked together and still remain
+loosely coupled.
+
+Also note that Toolkit has a nested setting - settings can be arranged in
+namespaces, however that makes sense.
+
+{Mattock::TaskLib} also codifies the typical pattern with Rake tasklibs: setup
+default configuration, yield self, confirm configs, define tasks.
+Configuration is held in "settings," which mean defaults are easier to track,
+complex configs can be resolved after setup, and required values automatically
+confirmed.
+
+A nice side effect is that "misconfiguration" - i.e. assigning a
+value to the wrong name - gets caught really quickly, which you come to
+appreciate in complex Rakefiles.
+
+=== Tasks
+
+{Mattock::Task} defines subclasses of Rake tasks - they can do all the
+configuration that Mattock::TaskLib can, but they're just tasks.  Crucially,
+details about whether they're needed can be overriden.  Occasionally handy.

data/lib/mattock/configurable.rb

@@ -5,6 +5,9 @@ module Mattock
   #nil).  Settings and their defaults are inherited (and can be overridden) by
   #subclasses.
   #
+  #Mattock also includes a yard-extension that will document settings of a
+  #Configurable
+  #
   #@example (see ClassMethods)
   module Configurable
     RequiredField = Object.new
@@ -22,7 +25,7 @@ module Mattock
     #Describes class level DSL & machinery for working with configuration
     #managment.
     #
-    #@example Quick example
+    #@example
     #    class ConfExample
     #      include Configurable
     #

data/lib/mattock/task.rb

@@ -64,7 +64,7 @@ module Mattock
 
     def define
       task = task_class.define_task(*task_args) do
-        action
+        task.action
       end
       copy_settings_to(task)
     end

data/lib/mattock/tasklib.rb

@@ -3,13 +3,7 @@ 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
+  #them in multiple projects.
   #
   #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
@@ -24,8 +18,15 @@ module Mattock
   #
   #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:
+  #components.
+  #
+  #@example
+  #    CoolTask.new(:args) do |t|
+  #      t.option_one = "cool"
+  #      t.option_two = "very"
+  #    end
   #
+  #@example Composition
   #    transport = HTTPTasks.new do |t|
   #      t.server = http://mycoolserver.com
   #    end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mattock
 version: !ruby/object:Gem::Version
-  version: 0.2.12
+  version: 0.2.13
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-16 00:00:00.000000000 Z
+date: 2012-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: corundum
-  requirement: &71422620 !ruby/object:Gem::Requirement
+  requirement: &76587950 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 0.0.1
   type: :development
   prerelease: false
-  version_requirements: *71422620
+  version_requirements: *76587950
 - !ruby/object:Gem::Dependency
   name: valise
-  requirement: &71421560 !ruby/object:Gem::Requirement
+  requirement: &76587340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0.6'
   type: :runtime
   prerelease: false
-  version_requirements: *71421560
+  version_requirements: *76587340
 - !ruby/object:Gem::Dependency
   name: tilt
-  requirement: &71545240 !ruby/object:Gem::Requirement
+  requirement: &76587100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>'
@@ -45,7 +45,7 @@ dependencies:
         - 0
   type: :runtime
   prerelease: false
-  version_requirements: *71545240
+  version_requirements: *76587100
 description: ! "  If Rake won't do it by itself, you oughtta Mattock.\n\n  If you
   survived the pun, you might enjoy this gem.\n\n  Features:\n\n  * Extensions to
   Tasklibs to support powerful deerpaths.\n  * A commandline library that supports
@@ -98,7 +98,7 @@ rdoc_options:
 - --main
 - doc/README
 - --title
-- mattock-0.2.12 RDoc
+- mattock-0.2.13 RDoc
 require_paths:
 - lib/
 required_ruby_version: !ruby/object:Gem::Requirement
@@ -109,7 +109,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -458443345
+      hash: 332286803
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: