tap 0.12.0 → 0.12.1

data/History

@@ -1,3 +1,11 @@
+== 0.12.1 / 2009-02-18
+
+Maintenance release with updates to Dump and Load tasks.
+
+* refactored Dump as CoreDump
+* implemented a simple yaml Dump
+* simplified Load
+
 == 0.12.0 / 2009-02-17
 
 As of the 0.12.0 release, Tap is distributed as several independent modules

data/README

@@ -52,6 +52,7 @@ Tap pulls documentation out of task classes to generate manifests:
     sample:
       goodnight   # your basic goodnight moon task
     tap:
+      core_dump   # dumps the application
       dump        # the default dump task
       load        # the default load task
       

data/lib/tap/tasks/core_dump.rb

@@ -0,0 +1,57 @@
+module Tap
+  module Tasks
+    # :startdoc::manifest dumps the application
+    #
+    # A dump task to print the application data to a file or IO.  Currently the
+    # dump result is only useful for viewing results.  In the future the core
+    # dump will be reloadable so a terminated app may restart execution.
+    #
+    # A core dump may be used in a terminal round to capture all the unhandled
+    # results from previous rounds; if no filepath is specified, the results
+    # are printed to stdout.
+    #  
+    #   % tap run -- [tasks] --+ core_dump FILEPATH
+    #
+    class CoreDump < Tap::FileTask
+      
+      config :date, true, &c.switch              # include a date
+      config :date_format, '%Y-%m-%d %H:%M:%S'   # the date format
+      config :info, true, &c.switch              # dump the app state information
+      config :aggregator, true, &c.switch        # dump aggregator results
+      config :audit, true, &c.switch             # include the audit trails with results
+      
+      def process(target=$stdout)
+        case target
+        when IO then dump_to(target)
+        when String
+          log_basename(:dump, target)
+          prepare(target)
+          File.open(target, "wb") {|file| dump_to(file) }
+        else
+          raise "cannot dump to: #{target.inspect}"
+        end
+      end
+    
+      def dump_to(io)
+        io.puts "# date: #{Time.now.strftime(date_format)}" if date
+        io.puts "# info: #{app.info}" if info
+        
+        if aggregator
+          trails = []
+          results = {}
+          app.aggregator.to_hash.each_pair do |src, _results|
+            results["#{src} (#{src.object_id})"] = _results.collect {|_audit| _audit.value }
+            _results.each {|_audit| trails << _audit.dump }
+          end
+      
+          if audit
+            io.puts "# audit:"
+            trails.each {|trail| io.puts "# #{trail.gsub("\n", "\n# ")}"}
+          end
+                
+          YAML::dump(results, io)
+        end
+      end
+    end
+  end
+end

data/lib/tap/tasks/dump.rb

@@ -1,61 +1,116 @@
-module Tap
-  module Tasks
-    # :startdoc::manifest the default dump task
-    #
-    # A dump task to print aggregated application results to a file or IO.  
-    # The results are printed as YAML, allowing dumped results to be 
-    # reloaded and used as inputs to other tasks.
-    #
-    # Often dump is used as the final task in a round of tasks; if no filepath 
-    # is specified, the results are printed to stdout.
-    #  
-    #   % tap run -- [tasks] --+ dump FILEPATH
-    #
-    # See Load for more details.
-    class Dump < Tap::FileTask
-      
-      config :date_format, '%Y-%m-%d %H:%M:%S'   # the date format
-      config :audit, true, &c.switch             # include the audit trails
-      config :date, true, &c.switch              # include a date
-      config :filter, nil, &c.regexp_or_nil      # only dump matching objects
-      
-      # Calls dump_to with the target.  If the target is not an
-      # IO, process assumes the target is a filepath.  In that
-      # case, the file is prepared and the results dumped to it.
-      def process(target=$stdout)
-        case target
-        when IO then dump_to(target)
-        else
-          log_basename(:dump, target)
-          prepare(target)
-          File.open(target, "wb") {|file| dump_to(file) }
-        end
-      end
-    
-      # Dumps the current results in app.aggregator to the io.
-      # The dump will include the result audits and a date,
-      # as specified in config.
-      def dump_to(io)
-        trails = []
-        results = {}
-        app.aggregator.to_hash.each_pair do |src, _results|
-          next if filter && src.to_s !~ filter
-          
-          results["#{src} (#{src.object_id})"] = _results.collect {|_audit| _audit.value }
-          _results.each {|_audit| trails << _audit.dump }
-        end
-      
-        if audit
-          io.puts "# audit:"
-          trails.each {|trail| io.puts "# #{trail.gsub("\n", "\n# ")}"}
-        end
-        
-        if date
-          io.puts "# date: #{Time.now.strftime(date_format)}"
-        end
-        
-        YAML::dump(results, io)
-      end
-    end
-  end
+module Tap
+  module Tasks
+    # :startdoc::manifest the default dump task
+    #
+    # A dump task to print results as YAML.  Unlike most tasks, dump arguments
+    # do not enque to the task; instead the arguments are used to setup a
+    # dump and the dump uses whatever results come to them in a workflow.
+    #
+    # Multiple dumps to the same file append rather than overwrite.  If no file
+    # is specified, the dump goes to $stdout.
+    #
+    #   % tap run -- [task] --: dump FILEPATH
+    #
+    # :startdoc::manifest-
+    #
+    # Dumps are organized so that arguments passed on the command line are
+    # directed at setup rather than process.  Moreover, process will always
+    # receive the audits passed to _execute, rather than the audit values.
+    # This allows a user to provide setup arguments (such as a dump path)
+    # on the command line, and provides dump the opportunity to inspect
+    # audit trails.
+    #
+    class Dump < Tap::FileTask
+      class << self
+        
+        # Same as an ordinary parse!, except the arguments normally reserved for
+        # executing the task are used to call setup.  The return will always be
+        # an instance and an empty array.
+        def parse!(argv=ARGV, app=Tap::App.instance)
+          instance, args = super
+          instance.setup(*args)
+          [instance, []]
+        end
+      end
+      
+      config :date_format, '%Y-%m-%d %H:%M:%S'   # the date format
+      config :audit, true, &c.switch             # include the audit trails
+      config :date, true, &c.switch              # include a date
+      
+      # The dump target, by default $stdout.  Target may be a filepath,
+      # in which case dumps append the file.
+      attr_accessor :target
+      
+      def initialize(config={}, name=nil, app=App.instance, target=$stdout)
+        super(config, name, app)
+        @target = target
+      end
+      
+      # Setup self with the input target.  Setup is typically called from
+      # parse! and receives arguments passed from the command line.
+      def setup(path=target)
+        @target = path
+      end
+      
+      # Overrides the standard _execute to send process the audits and not
+      # the audit values.  This allows process to inspect audit trails.
+      def _execute(*inputs)
+        resolve_dependencies
+        
+        previous = []
+        inputs.collect! do |input| 
+          if input.kind_of?(Support::Audit) 
+            previous << input
+            input.value
+          else
+            previous << Support::Audit.new(nil, input)
+            input
+          end
+        end
+        
+        # this is the overridden part
+        send(method_name, *previous)
+        audit = Support::Audit.new(self, inputs, previous)
+        
+        if complete_block = on_complete_block || app.on_complete_block
+          complete_block.call(audit)
+        else 
+          app.aggregator.store(audit)
+        end
+        
+        audit
+      end
+      
+      # Prints the _audit to the target.  The return value of process is
+      # not recorded in the audit trail.
+      def process(*_audits)
+        open_io do |io|
+          if date
+            io.puts "# date: #{Time.now.strftime(date_format)}"
+          end
+          
+          _audits.each do |_audit|
+            if audit
+              io.puts "# audit:"
+              io.puts "# #{_audit.dump.gsub("\n", "\n# ")}"
+            end
+          
+            YAML::dump(_audit.value, io)
+          end
+        end
+      end
+      
+      protected
+      
+      # helper to open and yield the io specified by target.  open_io
+      # ensures file targets are closed when the block returns.
+      def open_io # :nodoc:
+        case target
+        when IO, StringIO then yield(target)
+        when String then File.open(target, 'a') {|io| yield(io) }  
+        else raise "cannot open target: #{target.inspect}"
+        end
+      end
+    end
+  end
 end

data/lib/tap/tasks/load.rb

@@ -2,110 +2,23 @@ module Tap
   module Tasks
     # :startdoc::manifest the default load task
     #
-    # Load YAML-formatted data, as may be produced using Dump, and makes this
-    # data available for other tasks.  Load is often used as a gateway task
-    # to other tasks.
+    # Loads YAML-formatted data and makes the result available for other tasks.
+    # Load is typically used as a gateway task to other tasks.
     #
     #   % tap run -- load FILEPATH --: [task]
     #
-    # Load can select items from Hash or Array objects using one or more keys
-    # when only a subset is desired.  By default items are selected using [].
-    # For more flexible selection, use match.
-    # 
-    # Match converts each of the keys to a Regexp.  For hashes, all values
-    # with a matching key will be selected.  For arrays, any item matching
-    # a regexp will be selected.
-    #
-    # Use the flags to flatten, compact, sort (etc) results before passing
-    # them on to the next task.
     class Load < Tap::Task
       
-      config :match, false, :short => :m, &c.switch      # match keys
-      config :flatten, false, :short => :f, &c.switch    # flatten results
-      config :compact, false, :short => :c, &c.switch    # compact results
-      config :unique, false, :short => :u, &c.switch     # uniq results
-      config :sort, false, :short => :s, &c.switch       # sort results
-      #config :preview, false, :short => :p, &c.switch    # logs result
-      
-      # Loads the input as YAML and selects objects using keys.  Input may
-      # be an IO, StringIO, or a filepath.  If keys are empty, the loaded
-      # object is returned directly.
-      #
-      # ==== Key Selection
-      # Keys select items from the loaded object using [] (ie obj[key]).
-      # If match==true, the behavior is different; each string key is
-      # converted into a Regexp and then arrays select items that match
-      # key:
-      #
-      #   results = []
-      #   array.each {|i| results << i if i =~ key}
-      #
-      # While hashes select values where the key matches key:
-      #
-      #   results = []
-      #   hash.each_pair {|k,v| results << v if k =~ key}
-      #
-      # Other objects raise an error when match is true.  
-      #
-      # ==== Post Processing
-      # After loading/key selection, the results may be processed (in this
-      # order) using flatten, compact, unique, and sort, each performing as
-      # you would expect.  
-      # 
-      def process(input, *keys)
-        
-        # load the input
-        obj = case input
+      # Loads the input as YAML.  Input may be an IO, StringIO, or a filepath.
+      # The loaded object is returned directly.
+      def process(input)
+        case input
         when StringIO, IO
           YAML.load(input.read)
         else
           log :load, input
           YAML.load_file(input)
         end
-        
-        # select results by key
-        results = case
-        when keys.empty? then obj
-        when match 
-          regexps = keys.collect {|key| Regexp.new(key.to_s) }
-          select_matching(obj, regexps)
-        else 
-          keys.collect do |key| 
-            index = key.kind_of?(String) ? YAML.load(key) : key
-            obj[index]
-          end
-        end
-        
-        # post-process results
-        results = results.flatten if flatten
-        results = results.compact if compact
-        results = results.uniq if unique
-        results = results.sort if sort
-        
-        #if preview
-          # should be a log or something
-          #puts results.inspect
-        #end
-        
-        results
-      end
-      
-      protected
-      
-      # selects items from obj which match one of the regexps.
-      def select_matching(obj, regexps) # :nodoc:
-        case obj
-        when Array
-          obj.select {|item| regexps.any? {|r| item =~ r} }
-        when Hash
-          results = []
-          obj.each_pair do |key, value|
-            results << value if regexps.any? {|r| key =~ r}
-          end
-          results
-        else
-          raise ArgumentError, "cannot match keys from a #{obj.class}"
-        end
       end
     end 
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: tap
 version: !ruby/object:Gem::Version 
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors: 
 - Simon Chiang
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-02-17 00:00:00 -07:00
+date: 2009-02-18 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -96,6 +96,7 @@ files:
 - lib/tap/support/templater.rb
 - lib/tap/support/versions.rb
 - lib/tap/task.rb
+- lib/tap/tasks/core_dump.rb
 - lib/tap/tasks/dump.rb
 - lib/tap/tasks/load.rb
 - lib/tap/test.rb