tap 0.10.1 → 0.11.0

data/lib/tap/support/schema.rb

@@ -0,0 +1,359 @@
+require 'tap/support/node'
+require 'tap/support/joins'
+autoload(:Shellwords, 'shellwords')
+
+module Tap
+  module Support
+    autoload(:Parser, 'tap/support/parser')
+    
+    class Schema
+      module Utils
+        module_function
+        
+        # Shell quotes the input string by enclosing in quotes if
+        # str has no quotes, or double quotes if str has no double
+        # quotes.  Returns the str if it has not whitespace, quotes
+        # or double quotes.
+        #
+        # Raises an ArgumentError if str has both quotes and double
+        # quotes.
+        def shell_quote(str)
+          return str unless str =~ /[\s'"]/
+
+          quote = str.include?("'")
+          double_quote = str.include?('"')
+
+          case
+          when !quote then "'#{str}'"
+          when !double_quote then "\"#{str}\""
+          else raise ArgumentError, "cannot shell quote: #{str}"
+          end
+        end
+        
+        # Formats a round string.
+        #
+        #   format_round(1, [1,2,3])            # => "+1[1,2,3]"
+        #
+        def format_round(round, indicies)
+          "+#{round}[#{indicies.join(',')}]"
+        end
+
+        # Formats a sequence string.
+        #
+        #   format_sequence(1, [2,3], {})       # => "1:2:3"
+        #
+        def format_sequence(source_index, target_indicies, options)
+          ([source_index] + target_indicies).join(":") + format_options(options)
+        end
+
+        # Formats a global instance string.
+        #
+        #   format_instance(1)                  # => "*1"
+        #
+        def format_instance(index)
+          "*#{index}"
+        end
+
+        # Formats a fork string.
+        #
+        #   format_fork(1, [2,3],{})            # => "1[2,3]"
+        #
+        def format_fork(source_index, target_indicies, options)
+          "#{source_index}[#{target_indicies.join(',')}]#{format_options(options)}"
+        end
+
+        # Formats a merge string (note the target index is
+        # provided first).
+        #
+        #   format_merge(1, [2,3],{})           # => "1{2,3}"
+        #
+        def format_merge(target_index, source_indicies, options)
+          "#{target_index}{#{source_indicies.join(',')}}#{format_options(options)}"
+        end
+
+        # Formats a sync_merge string (note the target index 
+        # is provided first).
+        #
+        #   format_sync_merge(1, [2,3],{})      # => "1(2,3)"
+        #
+        def format_sync_merge(target_index, source_indicies, options)
+          "#{target_index}(#{source_indicies.join(',')})#{format_options(options)}"
+        end
+
+        # Formats an options hash into a string.  Raises an error
+        # for unknown options.
+        #
+        #   format_options({:iterate => true})  # => "i"
+        #
+        def format_options(options)
+          options_str = []
+          options.each_pair do |key, value|
+            unless index = Join::FLAGS.index(key)
+              raise "unknown key in: #{options} (#{key})"
+            end
+            
+            if value
+              options_str << Join::SHORT_FLAGS[index]
+            end
+          end
+          options_str.sort.join
+        end
+      end
+      
+      include Utils
+      
+      class << self
+        def parse(argv=ARGV)
+          Support::Parser.new(argv).schema
+        end
+
+        def load(argv)
+          parser = Parser.new
+          parser.load(argv)
+          parser.schema
+        end
+
+        def load_file(path)
+          argv = YAML.load_file(path)
+          load(argv)
+        end
+      end
+      
+      # An array of the nodes registered in self.
+      attr_reader :nodes
+
+      def initialize(nodes=[])
+        @nodes = nodes
+        @current_index = 1
+      end
+      
+      # Retrieves the node at index, or instantiates
+      # a new Node if one does not already exists.
+      def [](index)
+        nodes[index] ||= Node.new
+      end
+      
+      # Sets a join between the source and targets.  
+      # Returns the new join.
+      def set(join_class, source_indicies, target_indicies, options={})
+        join = join_class.new(options)
+
+        [*source_indicies].each {|source_index| self[source_index].output = join }
+        [*target_indicies].each {|target_index| self[target_index].input = join  }
+
+        join
+      end
+      
+      # Removes all nil nodes, and nodes with empty argvs.
+      # Additionally reassigns rounds by shifting later
+      # rounds up to fill any nils in the rounds array.
+      #
+      # Returns self.
+      def compact
+        # remove nil and empty nodes
+        nodes.delete_if do |node|
+          node == nil || node.argv.empty?
+        end
+        
+        # reassign rounds
+        index = 0
+        rounds.compact.each do |round|
+          round.each {|node| node.round = index }
+          index += 1
+        end
+        
+        self
+      end
+      
+      # Returns an array of the argvs for each nodes.
+      def argvs
+        nodes.collect do |node|
+          node == nil ? nil : node.argv
+        end
+      end
+      
+      # Returns a collection of nodes sorted  
+      # into arrays by node.round.
+      def rounds(as_indicies=false)
+        rounds = []
+        nodes.each do |node|
+          (rounds[node.round] ||= []) << node if node && node.round
+        end
+        
+        rounds.each do |round|
+          next unless round
+          round.collect! {|node| nodes.index(node) }
+        end if as_indicies
+
+        rounds
+      end
+      
+      # Returns a collection of global nodes
+      # (nodes with no input or output set).
+      def globals(as_indicies=false)
+        globals = []
+        nodes.each do |node|
+          globals << node if node && node.global?
+        end
+        
+        globals.collect! do |node| 
+          nodes.index(node)
+        end if as_indicies
+        
+        globals
+      end
+      
+      # Returns a hash of [join, [source_node, target_nodes]] pairs
+      # across all nodes.
+      def joins(as_indicies=false)
+        joins = {}
+        nodes.each do |node|
+          next unless node
+          
+          case node.input
+          when Join, ReverseJoin
+            (joins[node.input] ||= [nil,[]])[1] << node
+          end
+          
+          case node.output
+          when Join, ReverseJoin
+            (joins[node.output] ||= [nil,[]])[0] = node
+          end
+        end
+        
+        if as_indicies
+          summary = []
+          joins.each_pair do |join, (source_node, target_nodes)|
+            target_indicies = target_nodes.collect {|node| nodes.index(node) }
+            summary << [join.name, nodes.index(source_node), target_indicies, join.options]
+          end
+          
+          summary.sort_by {|entry| entry[1] || -1 }
+        else
+          joins
+        end
+      end
+      
+      def build(app)
+        tasks = {}
+        
+        # instantiate the nodes
+        nodes.each do |node|
+          tasks[node] = yield(node.argv) if node
+        end
+        
+        # instantiate and reconfigure globals
+        instances = []
+        globals.each do |node|
+          task, args = tasks.delete(node)
+          instance = task.class.instance
+          
+          if instances.include?(instance)
+            raise "global specified multple times: #{instance}"
+          end
+          
+          instance.reconfigure(task.config.to_hash)
+          instance.enq(*args)
+          instances << instance
+        end
+
+        # build the workflow
+        joins.each_pair do |join, (source_node, target_nodes)|
+          raise "unassigned join: #{join}" if source_node == nil
+
+          targets = target_nodes.collect do |target_node|
+            tasks[target_node][0]
+          end
+          source = tasks[source_node][0]
+          
+          join.join(source, targets)
+        end
+
+        # build queues
+        queues = rounds.compact.collect do |round|
+          round.each do |node|
+            task, args = tasks.delete(node)
+            task.enq(*args)
+          end
+
+          app.queue.clear
+        end
+        
+        # notify any args that will be overlooked
+        tasks.each_pair do |node, (task, args)|
+          next if args.empty?
+          warn "warning: ignoring args for node (#{nodes.index(node)}) #{task} [#{args.join(' ')}]"
+        end
+
+        queues
+      end
+      
+      # Creates an array dump of the contents of self.
+      def dump
+        segments = argvs
+        each_schema_str {|str| segments << str }
+        segments
+      end
+      
+      # Constructs a command-line string for the schema, ex:
+      # '-- a -- b --0:1'.
+      def to_s
+        segments = []
+        nodes.each do |node|
+          segments << "--"
+          
+          node.argv.each do |arg| 
+            segments << shell_quote(arg)
+          end unless node == nil
+        end
+        
+        each_schema_str {|str| segments << "--#{str}" }
+        segments.join(' ')
+      end
+      
+      protected
+      
+      # Yields each formatted schema string (global, round, and join).
+      def each_schema_str # :nodoc:
+        each_globals_str {|str| yield str }
+        each_round_str   {|str| yield str }
+        each_join_str    {|str| yield str }
+      end
+      
+      # Yields globals formatted as a string.
+      def each_globals_str # :nodoc:
+        globals.each do |node|
+          yield format_instance(nodes.index(node))
+        end
+      end
+      
+      # Yields each round formatted as a string.
+      def each_round_str # :nodoc
+        index = 0
+        rounds.each do |indicies|
+          unless indicies == nil || index == 0
+            indicies = indicies.collect {|node| nodes.index(node) }
+            yield format_round(index, indicies)
+          end
+          index += 1
+        end
+      end
+
+      # Yields each join formatted as a string.
+      def each_join_str # :nodoc
+        joins.each_pair do |join, (source_node, target_nodes)|
+          source_index = nodes.index(source_node)
+          target_indicies = target_nodes.collect {|node| nodes.index(node) }
+          
+          yield case join
+          when Joins::Sequence   then format_sequence(source_index, target_indicies, join.options)
+          when Joins::Fork       then format_fork(source_index, target_indicies, join.options)
+          when Joins::Merge      then format_merge(source_index, target_indicies, join.options)
+          when Joins::SyncMerge  then format_sync_merge(source_index, target_indicies, join.options)
+          else raise "unknown join type: #{join.class} (#{source_index}, [#{target_indicies.join(',')}])"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tap/support/shell_utils.rb

@@ -4,8 +4,7 @@ module Tap
   module Support
     # Provides several shell utility methods for calling programs.
     #
-    # == Windows
-    # A couple warnings when running shell commands in the MSDOS prompt on Windows.  
+    # == Windows 
     # MSDOS has command line length limits specific to the version of Windows being
     # run (from http://www.ss64.com/nt/cmd.html):
     #
@@ -13,9 +12,8 @@ module Tap
     # Windows 2000::  2046 characters
     # Windows XP:: 8190 characters
     #
-    # No word on more recent versions of Windows.  Commands longer than these limits
-    # fail, usually with something like: 'the input line is too long'
-    #
+    # Commands longer than these limits fail, usually with something like: 'the input
+    # line is too long'
     module ShellUtils
       
       module_function

data/lib/tap/support/string_ext.rb

@@ -0,0 +1,60 @@
+module Tap
+  module Support
+    
+    # StringExt provides two common string transformations, camelize and
+    # underscore. StringExt is automatically included in String.
+    #
+    # Both methods are directly taken from the ActiveSupport {Inflections}[http://api.rubyonrails.org/classes/ActiveSupport/CoreExtensions/String/Inflections.html]
+    # module.  StringExt should not cause conflicts if ActiveSupport is
+    # loaded alongside Tap.
+    #
+    # ActiveSupport is distributed with an MIT-LICENSE:
+    #
+    #   Copyright (c) 2004-2008 David Heinemeier Hansson
+    # 
+    #   Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
+    #   associated documentation files (the "Software"), to deal in the Software without restriction, 
+    #   including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 
+    #   and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, 
+    #   subject to the following conditions:
+    # 
+    #   The above copyright notice and this permission notice shall be included in all copies or substantial 
+    #   portions of the Software.
+    # 
+    #   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT 
+    #   LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN 
+    #   NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
+    #   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
+    #   SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+    #
+    module StringExt
+      
+      # camelize converts self to UpperCamelCase. If the argument to 
+      # camelize is set to :lower then camelize produces lowerCamelCase.
+      # camelize will also convert '/' to '::' which is useful for
+      # converting paths to namespaces.
+      def camelize(first_letter = :upper)
+        case first_letter
+        when :upper then self.to_s.gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
+        when :lower then self.first + camelize[1..-1]
+        end
+      end
+      
+      # The reverse of camelize. Makes an underscored, lowercase form 
+      # from self.  underscore will also change '::' to '/' to convert 
+      # namespaces to paths.
+      def underscore
+        self.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        tr("-", "_").
+        downcase
+      end
+      
+    end
+  end
+end
+
+class String # :nodoc:
+  include Tap::Support::StringExt
+end

data/lib/tap/support/tdoc.rb

@@ -47,6 +47,11 @@ else
   end
 end
 
+unless Object.const_defined?(:TokenStream)
+  TokenStream = RDoc::TokenStream
+  Options = RDoc::Options
+end
+
 module Tap
   module Support
   
@@ -79,7 +84,7 @@ module Tap
     # Now execute the rake task like:
     #
     #   % rake rdoc
-    #
+    #--
     # === Implementation
     # RDoc is a beast to utilize in a non-standard way. One way to make RDoc parse unexpected
     # flags like 'config' or 'config_attr' is to use the '--accessor' option (see 'rdoc --help' or 
@@ -129,7 +134,7 @@ module Tap
     
       # Encasulates information about the configuration.  Designed to be utilized
       # by the TDocHTMLGenerator as similarly as possible to standard attributes.
-      class ConfigAttr < RDoc::Attr
+      class ConfigAttr < RDoc::Attr # :nodoc:
         # Contains the actual declaration for the config attribute. ex:  "c [:key, 'value']      # comment"
         attr_accessor :config_declaration, :default
         

data/lib/tap/support/templater.rb

@@ -5,10 +5,9 @@ module Tap
   module Support
     
     # Templater is a convenience class for creating ERB templates.  As
-    # an OpenStruct, attributes can be assigned/unassigned at will to
-    # a Templater.  When the template is built, all the method of 
-    # Templater (and hence all the assigned attributes) are available
-    # in the template.
+    # a subclass of OpenStruct, attributes can be assigned/unassigned
+    # directly.  When the template is built, all the method of 
+    # Templater (and hence all the assigned attributes) are available.
     #
     #   t = Templater.new( "key: <%= value %>")
     #   t.value = "default"
@@ -23,16 +22,14 @@ module Tap
     #
     # Templater hooks into the ERB templating mechanism by providing itself 
     # as the ERB output target (_erbout).  ERB concatenates each line of an 
-    # ERB template to _erbout, as can be seen when you look at the src code 
-    # evaluated by ERB:
+    # ERB template to _erbout, as can be seen here:
     #
     #   e = ERB.new("<%= 1 + 2 %>")
     #   e.src                   # => "_erbout = ''; _erbout.concat(( 1 + 2 ).to_s); _erbout"
     #
-    # By setting itself as _erbout, instances of Templater can redirect the 
-    # output to a temporary target which can then be used in string 
-    # transformations.  For example, redirection allows indentation of 
-    # nested content:
+    # By setting itself as _erbout, instances of Templater can redirect 
+    # output to a temporary target and perform string transformations.  
+    # For example, redirection allows indentation of nested content:
     #
     #   template = %Q{
     #   # Un-nested content
@@ -62,10 +59,15 @@ module Tap
         # yamlize converts the object to YAML (using to_yaml), omitting
         # the header and final newline:
         #
-      	#   {'key' => 'value'}.to_yaml           # => "--- \nkey: value\n"
-      	#   yamlize {'key' => 'value'}           # => "key: value"
+        #   {'key' => 'value'}.to_yaml           # => "--- \nkey: value\n"
+        #   yamlize {'key' => 'value'}           # => "key: value"
         def yamlize(object)
-        	object.to_yaml[5...-1]
+          object == nil ? "~" : YAML.dump(object)[4...-1].strip
+        end
+        
+        # Comments out the string.
+        def comment(str)
+          str.split("\n").collect {|line| "# #{line}" }.join("\n")
         end
         
         # Nest the return of the block in the nesting lines.
@@ -117,6 +119,12 @@ module Tap
         end
       end
       
+      class << self
+        def build(template,  attributes={})
+          new(template, attributes).build
+        end
+      end
+      
       include Utils
       
       # Initialized a new Templater.  An ERB or String may be provided as the
@@ -124,8 +132,10 @@ module Tap
       # ERB with a trim_mode of "<>".
       def initialize(template, attributes={})
         @template = case template
-        when ERB 
-          if template.instance_variable_get(:@src).index('_erbout =') != 0
+        when ERB
+          # matching w/wo the coding effectively checks @src
+          # across ruby versions (encoding appears in 1.9)
+          if template.instance_variable_get(:@src) !~ /^(#coding:US-ASCII\n)?_erbout =/
             raise ArgumentError, "Templater does not work with ERB templates where eoutvar != '_erbout'"
           end
           template
@@ -170,7 +180,11 @@ module Tap
       
       # Build the template.  All methods of self will be 
       # accessible in the template.
-      def build
+      def build(attrs={})
+        attrs.each_pair do |key, value|
+          send("#{key}=", value)
+        end
+        
         @template.result(binding)
         @_erbout
       end

data/lib/tap/support/validation.rb

@@ -1,10 +1,12 @@
+autoload(:PP, 'pp')
+
 module Tap
   module Support
     
     # Validation generates blocks for common validations and transformations of 
-    # configurations set through Configurable.  In general these blocks allow
-    # configurations to be set to objects of a particular class, or to a string
-    # that can be loaded as YAML into such an object.
+    # configurations set through Configurable.  In general these blocks load
+    # string inputs as YAML and valdiate the results; non-string inputs are
+    # simply validated.
     #
     #   integer = Validation.integer
     #   integer.class             # => Proc
@@ -21,7 +23,6 @@ module Tap
     #
     # This syntax plays well with RDoc, which otherwise gets jacked 
     # when you do it all in one step.
-    #++
     module Validation
       
       # Raised when Validation blocks fail.
@@ -202,9 +203,11 @@ module Tap
       def boolean(); BOOLEAN; end
       BOOLEAN = yamlize_and_check(true, false, nil)
       
+      # Same as boolean.
       def switch(); SWITCH; end
       SWITCH = yamlize_and_check(true, false, nil)
       
+      # Same as boolean.
       def flag(); FLAG; end
       FLAG = yamlize_and_check(true, false, nil)
 
@@ -227,13 +230,20 @@ module Tap
       def array_or_nil(); ARRAY_OR_NIL; end
       ARRAY_OR_NIL = yamlize_and_check(Array, nil)
       
+      # Returns a block that checks the input is an array.
+      # If the input is a string the string is split along
+      # commas and each value yamlized into an array.
+      #
+      #   list.class                # => Proc
+      #   list.call([1,2,3])        # => [1,2,3]
+      #   list.call('1,2,3')        # => [1,2,3]
+      #   list.call('str')          # => ['str']
+      #   list.call(nil)            # => ValidationError
+      #
       def list(); LIST; end
       list_block = lambda do |input|
         if input.kind_of?(String)
-          input = case processed_input = yamlize(input)
-          when Array then processed_input
-          else input.split(/,/).collect {|arg| yamlize(arg) }
-          end
+          input = input.split(/,/).collect {|arg| yamlize(arg) }
         end
         
         validate(input, [Array])
@@ -405,6 +415,65 @@ module Tap
       end
       RANGE_OR_NIL = range_or_nil_block
       
+      # Returns a block that checks the input is a Time. String inputs are 
+      # loaded using Time.parse and then converted into times.  Parsed times 
+      # are local unless specified otherwise.
+      #
+      #   time.class               # => Proc
+      #
+      #   now = Time.now
+      #   time.call(now)           # => now
+      #
+      #   time.call('2008-08-08 20:00:00.00 +08:00').getutc.strftime('%Y/%m/%d %H:%M:%S')
+      #   #  => '2008/08/08 12:00:00'
+      #
+      #   time.call('2008-08-08').strftime('%Y/%m/%d %H:%M:%S')
+      #   #  => '2008/08/08 00:00:00'
+      #
+      #   time.call(1)             # => ValidationError
+      #   time.call(nil)           # => ValidationError
+      #
+      # Warning: Time.parse will parse a valid time (Time.now)
+      # even when no time is specified:
+      #
+      #   time.call('str').strftime('%Y/%m/%d %H:%M:%S')      
+      #   # => Time.now.strftime('%Y/%m/%d %H:%M:%S')      
+      #
+      def time()
+        # adding this here is a compromise to lazy-load the parse
+        # method (autoload doesn't work since Time already exists)
+        require 'time' unless Time.respond_to?(:parse)
+        TIME
+      end
+      
+      time_block = lambda do |input|
+        input = Time.parse(input) if input.kind_of?(String)
+        validate(input, [Time])
+      end
+      TIME = time_block
+      
+      # Same as time but allows nil:
+      #
+      #   time_or_nil.call('~')    # => nil
+      #   time_or_nil.call(nil)    # => nil
+      def time_or_nil()
+        # adding this check is a compromise to autoload the parse 
+        # method (autoload doesn't work since Time already exists)
+        require 'time' unless Time.respond_to?(:parse)
+        TIME_OR_NIL
+      end
+      
+      time_or_nil_block = lambda do |input|
+        input = case input
+        when nil, '~' then nil
+        when String then Time.parse(input)
+        else input
+        end
+        
+        validate(input, [Time, nil])
+      end 
+      TIME_OR_NIL = time_or_nil_block
+      
     end
   end
 end