tap 0.7.9

data/lib/tap/script/console.rb

@@ -0,0 +1,7 @@
+require "irb"
+
+def app
+  Tap::App.instance
+end
+
+IRB.start

data/lib/tap/script/destroy.rb

@@ -0,0 +1,8 @@
+require 'tap/generator'
+Rails::Generator::Base.use_tap_sources!
+
+require 'rails_generator/scripts/destroy'
+generator = ARGV.shift
+script = Rails::Generator::Scripts::Destroy.new
+script.extend Tap::Generator::Usage
+script.run(ARGV, :generator => generator)

data/lib/tap/script/generate.rb

@@ -0,0 +1,8 @@
+require 'tap/generator'
+Rails::Generator::Base.use_tap_sources!
+
+require 'rails_generator/scripts/generate'
+generator = ARGV.shift
+script = Rails::Generator::Scripts::Generate.new
+script.extend Tap::Generator::Usage
+script.run(ARGV, :generator => generator)

data/lib/tap/script/run.rb

@@ -0,0 +1,111 @@
+app = Tap::App.instance
+task_config = {}
+
+#
+# handle options
+#
+require 'getoptlong'
+
+opts = GetoptLong.new(
+['--app-config', '-a', GetoptLong::REQUIRED_ARGUMENT],# "Specifies an application config file"],
+['--config', '-c', GetoptLong::REQUIRED_ARGUMENT],# "Specifies configurations for the task."],
+['--quiet', '-q', GetoptLong::NO_ARGUMENT],# "Suppresses logging"],
+['--force', '-f', GetoptLong::NO_ARGUMENT],# "Force execution at checkpoints."],
+['--debug', '-d', GetoptLong::NO_ARGUMENT],# "Trace execution and debug."],
+['--help', '-h', GetoptLong::OPTIONAL_ARGUMENT])#, "Display help for app, or specified task."])
+
+opts.each do |opt, value| 
+  case opt
+  when '--help'
+    puts "help!"
+    exit
+  
+    if value.empty?
+      help
+    else
+      task = task(value)
+      puts task.class.help
+      puts "Default Config:"
+      puts task.class.default_config.stringify_keys.to_yaml
+    end
+  
+  when '--usage'
+    puts "usage!"
+    exit
+  
+  when '--app-config'
+    config = Tap::App.parse_yaml(value)
+    if config.kind_of?(String)
+      raise "application config file does not exist: #{config}" unless File.exists?(config)
+      config = Tap::App.read_erb_yaml(config)
+    end
+    app.reconfigure(config)
+  
+  when '--config'
+    task_config = Tap::App.parse_yaml(value)
+    if task_config.kind_of?(String)
+      raise "task config file does not exist: #{config}" unless File.exists?(config)
+      task_config = Tap::App.read_erb_yaml(config)
+    end
+
+  when '--quiet', '--force', '--debug'
+    # simply track these have been set
+    opt =~ /^-+(\w+)/
+    app.options.send("#{$1}=", true)
+  
+  else
+    puts "unknown option: #{opt}"
+    exit
+  end
+end
+
+#
+# gather arguments 
+# (be sure to clear for gets during interruption)
+
+if ARGV.empty?
+  puts "no task specified"
+  exit
+end
+
+td = ARGV.shift
+args = ARGV.collect {|arg| Tap::App.parse_yaml(arg) }
+ARGV.clear  
+
+task = app.task(td, task_config)
+
+#
+# set signals and run!
+#
+
+# info signal
+Signal.trap("INFO") do
+ puts app.info
+end
+
+# interuption signal
+Signal.trap("INT") do
+  puts " interrupted!"
+  # prompt for decision
+  while true
+    print "stop, terminate, or resume? (s/t/r):"
+    case gets.strip
+    when /s(top)?/i 
+      app.stop
+      break
+    when /t(erminate)?/i 
+      app.terminate
+      break
+    when /r(esume)?/i 
+      break
+    else
+      puts "unexpected response..."
+    end
+  end
+end
+
+puts "ctl-i prints information"
+puts "ctl-c interupts execution"
+puts "beginning run..."
+
+app.run(task, *args)

data/lib/tap/script/server.rb

@@ -0,0 +1,12 @@
+# change to the server dir so that script/server launches as normal
+# (otherwise Mongrel can raise errors because it can't find a log file)
+Dir.chdir Tap::App.instance[:server]
+
+server_script = "script/server"
+unless File.exists?(server_script)
+  puts "server script does not exist: #{Tap::App.instance.filepath(:server, server_script)}"
+  puts "no tap server available?"
+  exit
+end
+
+load server_script

data/lib/tap/support/audit.rb

@@ -0,0 +1,415 @@
+module Tap
+  module Support 
+
+    # === Overview
+    # 
+    # Audit tracks input and result values passed among tasks within a workflow.  At the end
+    # of a run, each result will have an audit trail detailing the values it has obtained
+    # at various stages, and the source of that value.  The ability to do track back all the
+    # places where a value was changed or modified is very important during workflow debugging.
+    #
+    # Audit is designed so you can ask a result 'hey where did you come from?' rather than 
+    # being able to ask an input 'what are all the results you ultimately produce?'. Say your 
+    # workflowconsists of 3 sequential tasks [:a, :b, :c]. Tasks :a and :b add one to their input
+    # value, while :c adds two.  Behind the scences, this is what happens when we run the workflow
+    # with an initial input value of 3:
+    #   
+    #   # task :a initializes a new audit with the original 
+    #   # value upon execution
+    #   ... run :a with input 3 ...
+    #   audit = Audit.new(3)
+    #
+    #   # when task :a finishes, it records the new value and 
+    #   # the source of the value (ie task ':a')
+    #   ... task :a adds one ...
+    #   audit._record(:a, 4)
+    #
+    #   # next the audit is passed to task :b, then task :c
+    #   # each of which records the next source and value
+    #   ... task :b adds one ...
+    #   audit._record(:b, 5)
+    #   ... task :c adds two ...
+    #   audit._record(:c, 7)
+    #   
+    #   # at the end, if you want to know how your final
+    #   # value got to be 7, you can look at the source_trail
+    #   # (note the very first source is nil)
+    #   audit._source_trail       # => [nil, :a, :b, :c]
+    #
+    # Audit supports forks by duplicating an audit trail (ie the recorded sources and values) and  
+    # merges by storing the various sources and values in an array.  For example:
+    #
+    #   # now let :a fork its results to both :b and :c
+    #   audit = Audit.new(3)
+    #   audit._record(:a, 4)
+    #   fork_b = audit._fork
+    #   fork_c = audit._fork 
+    #
+    #   ... tasks :b adds one and :c adds two ...
+    #   fork_b._record(:b, 5)
+    #   fork_c._record(:c, 6)
+    #
+    #   # at the end you have a separate source trail for 
+    #   # each result.
+    #   fork_b._source_trail      # => [nil, :a, :b]
+    #   fork_c._source_trail      # => [nil, :a, :c]
+    #
+    #   # now lets say you decided to merge both of
+    #   # these trails into a new task :d which adds
+    #   # all values that come to it.
+    #   ... task :d recieves results from :b and :c and adds them ...
+    #   merged_audit = Audit.merge(fork_b, fork_c)
+    #   merged_audit._record(:d, 11)
+    #
+    #   # now you can look back at the full source trail
+    #   # where an array of sources indicates two trails
+    #   # that merged
+    #   merged_audit._source_trail   # => [[[nil,:a,:b], [nil,:a,:c]], :d]
+    #
+    # An important thing to note is that while in these examples symbols have been used
+    # to represent the tasks, the actual tasks themselves are recorded as sources in practice.
+    # Thus the source trails can be used to access task configurations and other information
+    # that may be useful when assessing an audit. Incidentally, this is one of the reasons why Tap 
+    # is designed to be used with configurations that DO NOT change during execution; if they don't 
+    # change then you're able to look back at your handiwork.
+    #
+    # === Working with Audits
+    #
+    # Once an input enters the execution stream, it will be used to initialize an Audit.  
+    # From this point on, the Audit and not the value will be passed among tasks and ultimately
+    # passed out in the results array. 
+    #
+    # This must be kept in mind when building tasks into a workflow.  For convenience, Audits are 
+    # constructed to pass unknown methods and most comparision methods to the current value, such 
+    # that they behave like the current value.  It's important to realize that <em>workflow blocks 
+    # (ex: on_complete and condition) recieve Audits and NOT values</em>.
+    #
+    #   t = Tap::Task.new
+    #   t.on_complete do |results|
+    #     results.each do |result|
+    #       # you might expect result to be a value like 10 or "str"
+    #       # in fact it's an Audit, but it passes unknown methods
+    #       # along to it's current value
+    #
+    #       result.class            # => Audit
+    #       result._current         # => "str"
+    #       result == "str"         # => true
+    #       result.upcase           # => "STR"
+    #       
+    #       # the forwarding behavior is for convenience when 
+    #       # making decisions about what to do with a result
+    #       # but be sure you don't get caught!  The only object
+    #       # methods forwarded are '==' and '=~'.  Other methods
+    #       # are NOT forwarded, and =~ cannot (due to context 
+    #       # issues) capture match strings
+    #       
+    #       result.kind_of?(String) # => false
+    #       result =~ /s(\w+)/      # => true
+    #       $1                      # => nil  (watch out! you may expect "tr")
+    #  
+    #     end
+    #   end
+    # 
+    # Audits and NOT values are passed into these workflow blocks because you may need to make 
+    # a workflow decision based on where a value came from (ie you may need the source trail).  
+    # The same does not hold true when processing inputs.  <em>The process method recieves the 
+    # values themselves.</em>  
+    #
+    #   t = Tap::Task.new do |task, input|
+    #     # here in the process block, the input is the current value
+    #     # and NOT the Audit tracking the inputs and results
+    #     input.class               # => Fixnum  (given that we execute t with 3)
+    #     input += 1
+    #   end
+    #
+    #   results = t.execute(3)
+    #   results.class               # => Array
+    #   results.length              # => 1
+    #   results.first.class         # => Audit
+    #   results.first._current      # => 4
+    #
+    # === Summing it up:
+    #
+    # - Task inputs may be values or Audits
+    # - Task results are always an array of Audits
+    # - Workflow blocks (ex: on_complete and condition) recieve Audits and not values
+    # - The process method recieves the values themselves
+    #
+    class Audit
+      class << self
+
+        # Convenience method to create a new Audit for each of the inputs, if the 
+        # input is not already an Audit.  Returns an array of Audits.
+        def register(*inputs)
+          inputs.collect {|input| input.kind_of?(Audit) ? input : Audit.new(input) }
+        end
+
+        # Creates a new Audit from the inputs. The value of the new Audit will be the inputs
+        # array where any Audits are replaced by their _current value.  The source of the
+        # new Audit will be a corresponding array of nils, or Audits if provided.
+        #
+        #   a = Audit.new(1)
+        #   b = Audit.merge(a, 2)
+        #   b._values               # => [[1, 2]]
+        #   b._sources              # => [[a, nil]]
+        #
+        # If no inputs are provided, then merge a new Audit with an initial value of nil.
+        # If only one input is provided, then merge returns a new Audit initialized to
+        # the input, or a _fork of the input if it is already an Audit.
+        def merge(*inputs)
+          case inputs.length
+          when 0 then Audit.new
+          when 1
+            input = inputs.first
+            input.kind_of?(Audit) ? input._fork : Audit.new(input)
+          else
+            values = inputs.collect {|input| input.kind_of?(Audit) ? input._current : input}
+            sources =  inputs.collect {|input| input.kind_of?(Audit) ? input : nil}
+            Audit.new(values, sources)
+          end
+        end
+        
+      end
+      
+      attr_reader :_sources, :_values
+
+      # A new audit takes a value and/or source.  A nil source is typically given
+      # for the original value.  
+      def initialize(value=nil, source=nil)
+        @_sources = []
+        @_values = []
+        
+        _record(source, value)
+      end
+
+      # Records the next value produced by the source.  When an audit is
+      # passed as a value, record will record the current value of the audit.
+      # Record will similarly resolve every audit in an array containing audits.
+      #
+      # Example:
+      #
+      #    a = Audit.new(1)
+      #    b = Audit.new(2)
+      #    c = Audit.new(3)
+      #
+      #    c.record(:a, a) 
+      #    c.sources # => [:a]
+      #    c.values # => [1]
+      # 
+      #    c.record(:ab, [a,b])
+      #    c.sources # => [:a, :ab]
+      #    c.values # => [1, [1, 2]]
+      def _record(source, value)
+        _sources << source
+        _values << value
+        self
+      end
+
+      # The original value used to initialize the Audit
+      def _original
+        _values.first
+      end
+
+      # The current (ie last) value recorded in the Audit
+      def _current
+        _values.last
+      end
+
+      # The original source used to initialize the Audit
+      def _original_source
+        _sources.first
+      end
+      
+      # The current (ie last) source recorded in the Audit
+      def _current_source
+        _sources.last
+      end
+
+      # The index of the last occurence of source in the audit (Note
+      # equality is based on the object id of the specified source)
+      def _index_last(source)
+        _sources.rindex(source)
+      end
+
+      # The value recorded with the last occurence of source in the audit.  (Note
+      # equality is based on the object id of the specified source)
+      def _last(source)
+        index = _index_last(source)
+        index.nil? ? nil : _values[index]
+      end
+
+      # Returns the value at the specified index.
+      def _input(index)
+        _values[index]
+      end
+
+      # Returns the input to the last occurence of source in the audit (ie
+      # the value prior to this source).  Example:
+      #
+      #    a = Audit.new
+      #    a.record(:a, 'a') 
+      #    a.record(:b, 'b')
+      #
+      #    a.input_last(:a) # => nil
+      #    a.input_last(:b) # => 'a'
+      def _input_last(source)
+        index = _index_last(source)
+        _input(index-1)
+      end
+
+      # Returns the value after the specfied index
+      def _output(index)
+        _values[index+1]
+      end
+
+      # Returns the output of the last occurence of source in the audit (ie
+      # the value at this source).  Example:
+      #
+      #    a = Audit.new
+      #    a.record(:a, 'a') 
+      #    a.record(:b, 'b')
+      #
+      #    a.output_last(:a) # => 'a'
+      #    a.output_last(:b) # => 'b'
+      def _output_last(source)
+        index = _index_last(source)
+        _output(index-1)
+      end
+
+      # Searches back and recursively (if the source is an audit) collects all sources 
+      # for the current value.
+      def _source_trail
+        _sources.collect do |source|
+          source_trail(source)
+        end
+      end
+      
+      # Searches back and recursively (if the source is an audit) collects all values 
+      # leading to the current value.
+      def _value_trail
+        trail = []
+        0.upto(_sources.length-1) do |index|
+          trail << value_trail(_sources[index], _values[index])
+        end
+        trail
+      end
+
+      # Produces a new Audit suitable for development along a separate path, by merging 
+      # the input sources with self.  The value of the new audit will be an array of the 
+      # current values of the input sources and self.
+      #
+      # If no sources are provided, then _merge returns _fork.
+      def _merge(*sources)
+        sources.unshift(self)
+        Audit.merge(*sources)
+      end
+      
+      # Produces a new Audit with duplicate sources and values, suitable for
+      # separate development along a separate path.
+      def _fork
+        a = Audit.new
+        a._sources = _sources.dup
+        a._values = _values.dup
+        a
+      end
+
+      # Produces a new Audit from self and records the next value as
+      # the return value of the block.  The block itself will be recored
+      # as the value's source.
+      def _split(&block)
+        sp = Audit.new(nil, self)
+        sp._record(block, yield(_current))
+        sp
+      end
+
+      alias _eql ==
+      
+      # Compares _current with another using == 
+      def ==(another) 
+        _current == another 
+      end
+
+      alias _match =~
+      
+      # The method =~ does NOT work properly with an audit.  As with other 
+      # methods, =~ is aliased to work on _current.  However, variables like 
+      # $1, $2, etc cannot be passed back.  As a result:
+      #
+      #   a = Audit.new "abcd"
+      #   a =~ /ab(\w)/           # => true
+      #   $1                      # => nil (should be 'c')
+      #   
+      #   # instead use _current directly...
+      #   a._current =~ /ab(\w)/  # => true
+      #   $1                      # => 'c'
+      #
+      # Note the same applies to !~, as it executes through =~
+      def =~(regexp)
+        # note: this is not ideal... the variables $1, $2,
+        # etc are not sent back to the executing context (binding)
+        _current =~ regexp
+      end
+
+      # this shouldn't be necessary as Comparable feeds all it's methods
+      #include Comparable
+      
+      # Compares _current with another using <=> if <=> is defined
+      # for _current.  Otherwise returns 0.
+      #def <=>(another) 
+      #  _current.respond_to?(:<=>) ? _current <=> another : 0
+      #end
+
+      # CONSIDER FORWARDING ALL OF THESE!
+      # 
+      #[:eql?, :equal?, :is_a?, :kind_of?, :nil?, :respond_to?, :tainted?, :to_str].each do |method|
+      #  alias_name = "_#{method}".to_sym
+      #  alias alias_name method
+      #  define_method(method) do |*args|
+      #    _current.send(method, *args)
+      #  end
+      #end
+
+      #alias _cmp ===
+      #def ===(another) _current.send('===', another) end
+
+      protected  
+
+      attr_writer :_sources, :_values
+      
+      # Forwards all missing methods to _current
+      def method_missing(sym, *args, &block)
+        _current.send(sym, *args, &block)
+      end
+
+      private
+      
+      # helper method to recursively collect the source trail for a given source
+      def source_trail(source)
+        case source
+        when Array
+          source.collect {|s| source_trail(s)}
+        when Audit
+          source._source_trail
+        else
+          source
+        end
+      end
+      
+      # helper method to recursively collect the value trail for a given source
+      def value_trail(source, value)
+        case source
+        when Array
+          trail = []
+          0.upto(source.length-1) do |index|
+            trail << value_trail(source[index], value[index])
+          end
+          trail
+        when Audit
+          source._value_trail
+        else
+          value
+        end
+      end
+    end
+  end
+end