bahuvrihi-tap 0.10.8 → 0.11.0

data/History

@@ -1,3 +1,15 @@
+== 0.11.0 / 2008-10-20
+
+Significant update to Tap with many internal reworks.
+Major changes include:
+
+* Addition of Parser/Schema
+* Addition of rap and task declarations
+* Removal of Workflow in preference of workflow
+  definitions within Task
+* Refactoring of Test modules
+* Expanded/updated documentation
+
 == 0.10.1 / 2008-08-21
 
 Update of Tap with a few improvements to manifests

data/README

@@ -28,6 +28,8 @@ Check out these links for tutorials, development, and bug tracking.
 
 A simple task illustrates the usage of tap:
 
+  [lib/goodnight.rb]
+  
   # Goodnight::manifest your basic goodnight moon task
   # Says goodnight with a configurable message.
   class Goodnight < Tap::Task

data/bin/rap

@@ -15,7 +15,7 @@ begin
   task_file = File.expand_path('Tapfile')
   if File.exists?(task_file)
     env.loads.unshift(task_file)
-    env.tasks.register(Dir.pwd, task_file)
+    env.tasks.register(Dir.pwd, 'Tapfile')
   end
   
 rescue(Tap::Env::ConfigError)

data/doc/Class Reference

@@ -32,6 +32,10 @@ Instances of a Configurable class have a <tt>config</tt> method accessing a {Ins
     config :key, 'value' do |input|
       input.upcase
     end
+    
+    def initialize
+      initialize_config
+    end
   end
 
 Is basically the same as:
@@ -112,7 +116,7 @@ Lazydoc parses a constant name, the key, the value, and any comment following th
   lazydoc.resolve
 
   lazydoc['Name::Space']['key'].to_s           # => "This documentation gets parsed."
-  lazydoc['Name::Space']['another'].subject    # => "another value"
+  lazydoc['Name::Space']['another'].value      # => "another value"
 
 Furthermore, Lazydoc can register specific lines for documentation.  These lines are parsed to echo what happens in RDoc.
 
@@ -186,10 +190,12 @@ and batched.
   
 Batched tasks enque together, and therefore execute sequentially with the same inputs. Results are aggregated into the underlying Tap::App.
 
-  t1.execute('input')
-  runlist                  # => [t0, t1, t2, t3, t2]
+  t1.enq('input')
   
   app = Tap::App.instance
+  app.run
+  
+  runlist                  # => [t0, t1, t2, t3, t2]
   app.results(t2)          # => ["input:one:two", "input:three:two"]
 
 Tracking the evolution of a result through a workflow can get complex; Tap audits workflows to help.  In the audit trail, the tasks are identified by name.  Lets set the names of the tasks and take a look at the audit trails of the t2 results:
@@ -199,7 +205,7 @@ Tracking the evolution of a result through a workflow can get complex; Tap audit
   t3.name = 'trois'
   
   app._results(t2).collect do |_result|
-    _result.to_s
+    _result._to_s
   end.join("---\n")
   # => 
   # o-[] "input"
@@ -221,7 +227,7 @@ A Root represents the base of a directory structure. Roots allow you to alias di
   root = Tap::Root.new '/path/to/root'
   root.root                                      # => '/path/to/root'
   root['config']                                 # => '/path/to/root/config'
-  root.filepath('config', 'sample.yml')          # => '/path/to/root/config/sampl.yml'
+  root.filepath('config', 'sample.yml')          # => '/path/to/root/config/sample.yml'
 
 While simple, this ability to alias paths is useful, powerful, and forms the basis of the Tap execution environment.
 
@@ -261,15 +267,18 @@ Instances of Tap::App coordinate the execution of tasks.  Apps are basically a s
   log = StringIO.new
   app = Tap::App.instance
   app.logger = Logger.new(log)
+  app.logger.formatter = lambda do |severity, time, progname, msg|
+    "  %s %s: %s\n" % [severity[0,1], progname, msg]
+  end
   
   t = Tap::Task.intern {|task, *inputs| inputs }
   t.log 'action', 'to app'
-  log.string                 # =>  "  I[15:21:23]             action  to app\n"
+  log.string                 # =>  "  I action: to app\n"
   
   t.enq(1)
   t.enq(2,3)
   
-  app.queue.to_a             # => [[t, [1]], [t, [2,3]]
+  app.queue.to_a             # => [[t, [1]], [t, [2,3]]]
   app.run
   app.results(t)             # => [[1], [2,3]]
   

data/doc/Command Reference

@@ -27,7 +27,7 @@ Generate and destory launch generator scripts, similar to those in {Rails}[http:
 {command}[link:classes/Tap/Generator/Generators/CommandGenerator.html]:: a new command
 {config}[link:classes/Tap/Generator/Generators/ConfigGenerator.html]:: a static config file for the specified task
 {file_task}[link:classes/Tap/Generator/Generators/FileTaskGenerator.html]:: a file task and test
-{generator}[link:classes/Tap/Generator/GeneratorseneratorGenerator.html]:: a new generator
+{generator}[link:classes/Tap/Generator/Generators/GeneratorGenerator.html]:: a new generator
 {root}[link:classes/Tap/Generator/Generators/RootGenerator.html]:: the basic directory structure
 {task}[link:classes/Tap/Generator/Generators/TaskGenerator.html]:: a task class and test
 
@@ -68,7 +68,6 @@ Manifest prints a list of all resources (commands, tasks, generators, etc) avail
       generate       (cmd/generate.rb)
       manifest       (cmd/manifest.rb)
       run            (cmd/run.rb)
-      server         (cmd/server.rb)
     tasks
       dump           (lib/tap/tasks/dump.rb)
       load           (lib/tap/tasks/load.rb)

data/doc/Tutorial

@@ -86,8 +86,6 @@ Going back to the first example, lets take a look at how a task declaration maps
   
 Here is a corresponding class:
 
-  [Tapfile]
-  
   # Goodnight::manifest your basic goodnight moon task
   # Says goodnight with a configurable message.
   class Goodnight < Tap::Task
@@ -259,7 +257,7 @@ Run the test:
 
 Run the task:
 
-  % tap run -- goodnight moon
+  % rap goodnight moon
     I[23:22:19]          goodnight moon
 
 Ok, lets share it.  Print the current gemspec manifest:
@@ -269,7 +267,7 @@ Ok, lets share it.  Print the current gemspec manifest:
         Rakefile
         lib/goodnight.rb
         sample.gemspec
-        tap.yml
+  true  tap.yml
         test/goodnight_test.rb
   true  test/tap_test_helper.rb
   true  test/tap_test_suite.rb
@@ -284,7 +282,7 @@ As you can see, this needs an update to include the task file.  Open up sample.g
     s.platform = Gem::Platform::RUBY
     s.summary = "sample"
     s.require_path = "lib"
-    s.add_dependency("tap", "~> 0.10.8")
+    s.add_dependency("tap", ">= 0.11")
     s.files = %W{
       lib/goodnight.rb
       tap.yml

data/lib/tap/app.rb

@@ -6,91 +6,91 @@ require 'tap/support/executable_queue'
 module Tap
   
   # App coordinates the setup and running of tasks, and provides an interface 
-  # to the application directory structure.  App is convenient for use within 
-  # scripts and, with Env, provides the basis for the 'tap' command line 
-  # application.  
+  # to the application directory structure. All tasks have an App (by default
+  # App.instance) through which tasks access access application-wide resources 
+  # like the logger, executable queue, aggregator, and dependencies.
   #
   # === Running Tasks
   #
-  # All tasks have an App (by default App.instance) through which tasks access
-  # access application-wide resources like the logger.  Additionally, task
-  # enque command are forwarded to App#enq:
+  # Task enque command are forwarded to App#enq:
   #
-  #   t1 = Task.intern {|task, input| input += 1 }
-  #   t1.enq(0)
-  #   app.enq(t1, 1)
+  #   t0 = Task.intern {|task, input| "#{input}.0" }
+  #   t0.enq('a')
+  #   app.enq(t0, 'b')
   #
   #   app.run
-  #   app.results(t1)                # => [1, 2]
+  #   app.results(t0)                # => ['a.0', 'b.0']
   #
   # When a task completes, the results will be passed to the task on_complete
   # block, if set, or be collected into an Aggregator (aggregated results may 
-  # be accessed per-task, as shown above); on_complete blocks typically enque
-  # other tasks, allowing the construction of imperative workflows:
+  # be accessed per-task, as shown above); on_complete blocks typically 
+  # execute or enque other tasks, allowing the construction of imperative
+  # workflows:
   #
   #   # clear the previous results
   #   app.aggregator.clear
   #
-  #   t2 = Task.intern {|task, input| input += 10 }
-  #   t1.on_complete {|_result| t2.enq(_result) }
-  #
-  #   t1.enq 0
-  #   t1.enq 10
+  #   t1 = Task.intern {|task, input| "#{input}.1" }
+  #   t0.on_complete {|_result| t1.enq(_result) }
+  #   t0.enq 'c'
   #
   #   app.run
-  #   app.results(t1)                # => []
-  #   app.results(t2)                # => [11, 21]
+  #   app.results(t0)                # => []
+  #   app.results(t1)                # => ['c.0.1']
   #
-  # Here t1 has no results because the on_complete block passed them to t2 in 
+  # Here t0 has no results because the on_complete block passed them to t1 in 
   # a simple sequence.
   #
-  # ==== Dependencies
+  # === Dependencies
   #
-  # Tasks allow the construction of dependency-based workflows as well; tasks
-  # may be set to depend on other tasks such that the dependent task only 
-  # executes after the dependencies have been resolved.
+  # Tasks allow the construction of dependency-based workflows such that a 
+  # dependent task only executes after its dependencies have been resolved.
   #
-  #   array = []
-  #   t1 = Task.intern {|task, *inputs| array << inputs }
-  #   t2 = Task.intern {|task| array << self }
+  #   runlist = []
+  #   t0 = Task.intern {|task| runlist << task }
+  #   t1 = Task.intern {|task| runlist << task }
   #
-  #   t1.depends_on(t2)
-  #   t1.enq(4,5,6)
+  #   t0.depends_on(t1)
+  #   t0.enq
   #
   #   app.run
-  #   array                          # => [t2, [4,5,6]]
+  #   runlist                        # => [t1, t0]
   #
   # Once a dependency is resolved, it will not execute again:
   #
-  #   t1.enq(7,8)
+  #   t0.enq
   #   app.run
-  #   array                          # => [t2, [4,5,6], [7,8]]
+  #   runlist                        # => [t1, t0, t0]
   #
-  # ==== Batching
+  # === Batching
   #
   # Tasks can be batched, allowing the same input to be enqued to multiple 
   # tasks at once.
   #
-  #   t1 = Task.intern  {|task, input| input += 1 }
-  #   t2 = Task.intern  {|task, input| input += 10 }
+  #   t0 = Task.intern  {|task, input| "#{input}.0" }
+  #   t1 = Task.intern  {|task, input| "#{input}.1" }
   #
-  #   t1.batch_with(t2)
-  #   t1.enq 0
+  #   t0.batch_with(t1)
+  #   t0.enq 'a'
+  #   t1.enq 'b'
   #
   #   app.run
-  #   app.results(t1)                # => [1]
-  #   app.results(t2)                # => [10]
+  #   app.results(t0)                # => ['a.0', 'b.0']
+  #   app.results(t1)                # => ['a.1', 'b.1']
   #
-  # ==== Executables
+  # === Executables
   #
-  # App can enque and run any Executable object. One way to initialize an
-  # Executable for a method is to use the Object#_method added by Tap.
-  # The mq (method enq) method generates and enques the method in one step.
+  # App can enque and run any Executable object. Arbitrary methods may be
+  # made into Executables using Object#_method. The mq (method enq) method
+  # generates and enques methods in one step.
   #
   #   array = []
+  #
+  #   # longhand
   #   m = array._method(:push)
-  #    
-  #   app.enq(m, 1)
+  #   m.enq(1)
+  #
+  #   # shorthand
   #   app.mq(array, :push, 2)
   #
   #   array.empty?                   # => true
@@ -100,29 +100,29 @@ module Tap
   # === Auditing
   # 
   # All results are audited to track how a given input evolves during a workflow.
-  # To illustrate auditing, consider a workflow that uses the 'add_one' method 
-  # to add one to an input until the result is 3, then adds five more with the 
-  # 'add_five' method.  The final result should always be 8.  
-  #
-  #   t1 = Tap::Task.intern {|task, input| input += 1 }
-  #   t1.name = "add_one"
+  # To illustrate auditing, consider and addition workflow that ends in eights.
   #
-  #   t2 = Tap::Task.intern {|task, input| input += 5 }
-  #   t2.name = "add_five"
+  #   add_one  = Tap::Task.intern({}, 'add_one')  {|task, input| input += 1 }
+  #   add_five = Tap::Task.intern({}, 'add_five') {|task, input| input += 5 }
   #
-  #   t1.on_complete do |_result|
+  #   add_one.on_complete do |_result|
   #     # _result is the audit; use the _current method
   #     # to get the current value in the audit trail
+  #     current_value = _result._current
   #
-  #     _result._current < 3 ? t1.enq(_result) : t2.enq(_result)
+  #     if current_value < 3 
+  #       add_one.enq(_result)
+  #     else
+  #       add_five.enq(_result)
+  #     end
   #   end
   #   
-  #   t1.enq(0)
-  #   t1.enq(1)
-  #   t1.enq(2)
+  #   add_one.enq(0)
+  #   add_one.enq(1)
+  #   add_one.enq(2)
   #
   #   app.run
-  #   app.results(t2)                # => [8,8,8]
+  #   app.results(add_five)          # => [8,8,8]
   #
   # Although the results are indistinguishable, each achieved the final value
   # through a different series of tasks. With auditing you can see how each 
@@ -130,7 +130,7 @@ module Tap
   #
   #   # app.results returns the actual result values
   #   # app._results returns the audits for these values
-  #   app._results(t2).each do |_result|
+  #   app._results(add_five).each do |_result|
   #     puts "How #{_result._original} became #{_result._current}:"
   #     puts _result._to_s
   #     puts
@@ -257,10 +257,6 @@ module Tap
       name == nil ? nil : filepath('config', "#{name}.yml")
     end
     
-    #
-    # Execution methods
-    #
-    
     # Sets state = State::READY unless the app is running.  Returns self.
     def ready
       @state = State::READY unless state == State::RUN
@@ -337,10 +333,8 @@ module Tap
       "state: #{state} (#{State.state_str(state)}) queue: #{queue.size} results: #{aggregator.size}"
     end
     
-    # Enques the task with the inputs.  If the task is batched, then each 
-    # task in task.batch will be enqued with the inputs.  Returns task.
-    #
-    # An Executable may provided instead of a task.
+    # Enques the task (or Executable) with the inputs.  If the task is batched, 
+    # then each task in task.batch will be enqued with the inputs.  Returns task.
     def enq(task, *inputs)
       case task
       when Tap::Task
@@ -371,16 +365,17 @@ module Tap
     # Returns all aggregated results for the specified tasks.  Results are
     # joined into a single array.  Arrays of tasks are allowed as inputs.    
     #
-    #   t1 = Task.intern  {|task, input| input += 1 }
-    #   t2 = Task.intern  {|task, input| input += 10 }
-    #   t3 = t2.initialize_batch_obj
+    #   t0 = Task.intern  {|task, input| "#{input}.0" }
+    #   t1 = Task.intern  {|task, input| "#{input}.1" }
+    #   t2 = Task.intern  {|task, input| "#{input}.2" }
+    #   t1.batch_with(t2)
     #
-    #   t1.enq(0)
-    #   t2.enq(1)
+    #   t0.enq(0)
+    #   t1.enq(1)
     #
     #   app.run
-    #   app.results(t1, t2.batch)     # => [1, 11, 11]
-    #   app.results(t2, t1)           # => [11, 1]
+    #   app.results(t0, t1.batch)     # => ["0.0", "1.1", "1.2"]
+    #   app.results(t1, t0)           # => ["1.1", "0.0"]
     #
     def results(*tasks)
       _results(tasks).collect {|_result| _result._current}

data/lib/tap/constants.rb

@@ -1,7 +1,7 @@
 module Tap
   MAJOR = 0
-  MINOR = 10
-  TINY = 8
+  MINOR = 11
+  TINY = 0
   
   VERSION="#{MAJOR}.#{MINOR}.#{TINY}" 
   WEBSITE="http://tap.rubyforge.org"

data/lib/tap/env.rb

@@ -450,22 +450,22 @@ module Tap
     # be returned if the block returns true.
     #
     # Returns nil if no file can be found.
-    # def search_path(dir, path)
-    #   each do |env|
-    #     directory = env.root.filepath(dir)
-    #     file = env.root.filepath(dir, path)
-    #     
-    #     # check the file is relative to the
-    #     # directory, and that the file exists.
-    #     if file.rindex(directory, 0) == 0 && 
-    #       File.exists?(file) && 
-    #       (!block_given? || yield(file))
-    #       return file
-    #     end
-    #   end
-    #   
-    #   nil
-    # end
+    def search_path(dir, path)
+      each do |env|
+        directory = env.root.filepath(dir)
+        file = env.root.filepath(dir, path)
+        
+        # check the file is relative to the
+        # directory, and that the file exists.
+        if file.rindex(directory, 0) == 0 && 
+          File.exists?(file) && 
+          (!block_given? || yield(file))
+          return file
+        end
+      end
+      
+      nil
+    end
     
     # def reset(name, &block)
     #   each do |env|
@@ -474,30 +474,28 @@ module Tap
     #   end
     # end
     
-    TEMPLATES = {
-      :commands => %Q{<% if count > 1 %>
+    # 
+    TEMPLATES = {}
+    TEMPLATES[:commands] = %Q{<% if count > 1 %>
 <%= env_name %>:
 <% end %>
 <% entries.each do |name, const| %>
   <%= name.ljust(width) %>
-<% end %>},
-
-      :tasks => %Q{<% if count > 1 %>
+<% end %>}
+    TEMPLATES[:tasks] = %Q{<% if count > 1 %>
 <%= env_name %>:
 <% end %>
 <% entries.each do |name, const| %>
 <%   desc = const.document[const.name]['manifest'] %>
   <%= name.ljust(width) %><%= desc.empty? ? '' : '  # ' %><%= desc %>
-<% end %>},
-
-      :generators => %Q{<% if count > 1 %>
+<% end %>}
+    TEMPLATES[:generators] = %Q{<% if count > 1 %>
 <%= env_name %>:
 <% end %>
 <% entries.each do |name, const| %>
 <%   desc = const.document[const.name]['generator'] %>
   <%= name.ljust(width) %><%= desc.empty? ? '' : '  # ' %><%= desc %>
 <% end %>}
-    }
     
     def summarize(name, template=TEMPLATES[name])
       count = 0