bahuvrihi-tap 0.10.6 → 0.10.7

data/lib/tap/support/joins/merge.rb

@@ -0,0 +1,20 @@
+module Tap
+  module Support
+    module Joins
+
+      class Merge < ReverseJoin
+        def join(target, sources)
+          sources.each do |source|
+            # merging can use the existing audit trails... each distinct 
+            # input is getting sent to one place (the target)
+            complete(source) do |_result| 
+              yield(_result) if block_given?
+              enq(target, _result)
+            end
+          end
+        end
+      end
+      
+    end
+  end
+end

data/lib/tap/support/joins/sequence.rb

@@ -0,0 +1,21 @@
+module Tap
+  module Support
+    module Joins
+
+      class Sequence < Join
+        def join(source, targets)
+          current_task = source
+          targets.each do |next_task|
+            # simply pass results from one task to the next. 
+            complete(current_task) do |_result| 
+              yield(_result) if block_given?
+              enq(next_task, _result)
+            end
+            current_task = next_task
+          end
+        end
+      end
+      
+    end
+  end
+end

data/lib/tap/support/joins/switch.rb

@@ -0,0 +1,23 @@
+module Tap
+  module Support
+    module Joins
+
+      class Switch < Join
+        def join(source, targets)
+          complete(source) do |_result| 
+            if index = yield(_result)        
+              unless target = targets[index] 
+                raise "no switch target for index: #{index}"
+              end
+
+              enq(target, _result)
+            else
+              source.app.aggregator.store(_result)
+            end
+          end
+        end
+      end
+      
+    end
+  end
+end

data/lib/tap/support/joins/sync_merge.rb

@@ -0,0 +1,57 @@
+module Tap
+  module Support
+    module Joins
+      
+      class SyncMerge < ReverseJoin
+        def join(target, sources)
+
+          # a hash of (source, index) pairs where index is the
+          # index of the source in a combination
+          indicies = {}
+
+          # a hash of (source, combinations) pairs where combinations
+          # are combination arrays that the source participates in.
+          # note that in unbatched mode, some sources may not
+          # participate in any combinations.
+          combinations = {}
+
+          sets = sources.collect {|source| unbatched ? [source] : source.batch }
+          Support::Combinator.new(*sets).each do |combo|
+            combination = Array.new(combo.length, nil)
+
+            combo.each do |source|
+              indicies[source] ||= combo.index(source)
+              (combinations[source] ||= []) << combination
+            end
+          end
+
+          sources.each_with_index do |source, index|
+            complete(source) do |_result|
+              src = _result._current_source
+
+              source_index = indicies[src]
+              (combinations[src] ||= []).each do |combination|
+                if combination[source_index] != nil
+                  raise "sync_merge collision... already got a result for #{src}"
+                end
+
+                combination[source_index] = _result
+                unless combination.include?(nil)
+                  # merge the source audits
+                  _merge_result = Support::Audit.merge(*combination)
+
+                  yield(_merge_result) if block_given?
+                  enq(target, _merge_result)
+
+                  # reset the group array
+                  combination.collect! {|i| nil }
+                end
+              end
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/tap/support/lazydoc/document.rb

@@ -62,6 +62,16 @@ module Tap
         def [](const_name)
           const_attrs[const_name] ||= {}
         end
+        
+        # Returns an array of the const_names in self with at
+        # least one attribute.
+        def const_names
+          names = []
+          const_attrs.each_pair do |const_name, attrs|
+            names << const_name unless attrs.empty?
+          end
+          names
+        end
 
         # Register the specified line number to self.  Returns a 
         # comment_class instance corresponding to the line.

data/lib/tap/support/node.rb

@@ -0,0 +1,58 @@
+module Tap
+  module Support
+
+    # Represents a task node in a Schema.
+    class Node
+      
+      # An array of arguments used to instantiate
+      # the node, and to specify arguments enqued
+      # to the instance (when the node is directly
+      # enqued to a round... see input)
+      attr_accessor :argv
+      
+      # The input or source for the node.  Inputs
+      # may be a Join, nil, or an Integer (indicating
+      # the node should be enqued to a round, with 
+      # inputs as specified in argv).
+      attr_accessor :input
+      
+      # The output for the node. Output may be a
+      # a Join or nil.
+      attr_accessor :output
+
+      def initialize(argv=[], input=nil, output=nil)
+        @argv = argv
+        @input = input
+        @output = output
+      end
+      
+      # Resets the source and join to nil.
+      def globalize
+        self.input = nil
+        self.output = nil
+      end
+      
+      # True if the input and output are nil.
+      def global?
+        input == nil && output == nil
+      end
+      
+      # Returns the round for self; a round is indicated
+      # by an integer input.  If input is anything but 
+      # an integer, round returns nil.
+      def round
+        input.kind_of?(Integer) ? input : nil
+      end
+      
+      # Alias for input=
+      def round=(input)
+        self.input = input
+      end
+      
+      def inspect
+        "#<#{self.class}:#{object_id} argv=[#{argv.join(' ')}] input=#{input.inspect} output=#{output.inspect}>"
+      end
+
+    end
+  end
+end

data/lib/tap/support/parser.rb

@@ -0,0 +1,379 @@
+require 'tap/support/schema'
+autoload(:Shellwords, 'shellwords')
+
+module Tap
+  module Support
+    
+    # ==== Round Assignment
+    # Tasks can be defined and set to a round using the following:
+    #
+    #   break           assigns task(s)         to round
+    #   --              next                    0
+    #   --+             next                    1
+    #   --++            next                    2
+    #   --+2            next                    2
+    #   --+2[1,2,3]     1,2,3                   2
+    #
+    # Here all task (except c) are parsed into round 0, then the
+    # final argument reassigns e to round 3.
+    #
+    #   schema = Parser.new("a -- b --+ c -- d -- e --+3[4]").schema
+    #   schema.rounds(true)             # => [[0,1,3],[2], nil, [4]]
+    #
+    # ==== Workflow Assignment
+    # All simple workflow patterns except switch can be specified within
+    # the parse syntax (switch is the exception because there is no good
+    # way to define a block from an array).  
+    #
+    #   break      pattern       source(s)      target(s)
+    #   --:        sequence      last           next
+    #   --[]       fork          last           next
+    #   --{}       merge         next           last
+    #   --()       sync_merge    next           last
+    #
+    #   example       meaning
+    #   --1:2         1.sequence(2)
+    #   --1:2:3       1.sequence(2,3)
+    #   --:2:         last.sequence(2,next)
+    #   --[]          last.fork(next)
+    #   --1{2,3,4}    1.merge(2,3,4)
+    #   --(2,3,4)     last.sync_merge(2,3,4)
+    #
+    # Note how all of the bracketed styles behave similarly; they are
+    # parsed with essentially the same code, only reversing the source
+    # and target in the case of merges.
+    #
+    # Here a and b are sequenced inline.  Task c is assigned to no 
+    # workflow until the final argument which sequenced b and c.
+    #
+    #   schema = Parser.new("a --: b -- c --1:2i").schema
+    #   schema.argvs                    # => [["a"], ["b"], ["c"], []]
+    #   schema.joins(true)              # => [[:sequence,0,[1],{}], [:sequence,1,[2],{:iterate => true}]]
+    #
+    # ==== Globals
+    # Global instances of task (used, for example, by dependencies) may
+    # be assigned in the parse syntax as well.  The break for a global
+    # is '--*'.
+    #
+    #   schema = Parser.new("a -- b --* global_name --config for --global").schema
+    #   schema.globals(true)            # => [2]
+    #
+    # ==== Escapes and End Flags
+    # Breaks can be escaped by enclosing them in '-.' and '.-' delimiters;
+    # any number of arguments may be enclosed within the escape. After the 
+    # end delimiter, breaks are active once again.
+    #
+    #   schema = Parser.new("a -- b -- c").schema
+    #   schema.argvs                    # => [["a"], ["b"], ["c"]]
+    # 
+    #   schema = Parser.new("a -. -- b .- -- c").schema
+    #   schema.argvs                    # => [["a", "--", "b"], ["c"]]
+    #
+    # Parsing continues until the end of argv, or a an end flag '---' is 
+    # reached.  The end flag may also be escaped.
+    #
+    #   schema = Parser.new("a -- b --- c").schema
+    #   schema.argvs                    # => [["a"], ["b"]]
+    #
+    class Parser
+      
+      # A set of parsing routines used internally by Tap::Support::Parser,
+      # modularized for ease of testing, and potential re-use. These methods 
+      # require that <tt>current_index</tt> and <tt>previous_index</tt> be 
+      # implemented in the including class.
+      module Utils
+        module_function
+
+        # Defines a break regexp that matches a bracketed-pairs
+        # break.  The left and right brackets are specified as
+        # inputs.  After a match:
+        #
+        #   $1:: The source string after the break. 
+        #        (ex: '[]' => '', '1[]' => '1')
+        #   $2:: The target string. 
+        #        (ex: '[]' => '', '1[1,2,3]' => '1,2,3')
+        #   $3:: The modifier string.
+        #        (ex: '[]i' => 'i', '1[1,2,3]is' => 'is')
+        #
+        def bracket_regexp(l, r)
+          /\A(\d*)#{Regexp.escape(l)}([\d,]*)#{Regexp.escape(r)}([A-z]*)\z/
+        end
+
+        # The escape begin argument
+        ESCAPE_BEGIN = "-."
+
+        # The escape end argument
+        ESCAPE_END = ".-"
+
+        # The parser end flag
+        END_FLAG = "---"
+
+        # Matches any breaking arg (ex: '--', '--+', '--1:2')
+        # After the match:
+        #
+        #   $1:: The string after the break
+        #        (ex: '--' => '', '--++' => '++', '--1(2,3)' => '1(2,3)')
+        #
+        BREAK =  /\A--(\z|[\+\d\:\*\[\{\(].*\z)/
+
+        # Matches an execution-round break.  After the match:
+        #
+        #   $2:: The round string, or nil.
+        #        (ex: '' => nil, '++' => '++', '+1' => '+1')
+        #   $5:: The target string, or nil. 
+        #        (ex: '+' => nil, '+[1,2,3]' => '1,2,3')
+        #
+        ROUND = /\A((\+(\d*|\+*))(\[([\d,]*)\])?)?\z/
+
+        # Matches a sequence break.  After the match:
+        #
+        #   $1:: The sequence string after the break. 
+        #        (ex: ':' => ':', '1:2' => '1:2', '1:' => '1:', ':2' => ':2')
+        #   $3:: The modifier string.
+        #        (ex: ':i' => 'i', '1:2is' => 'is')
+        #
+        SEQUENCE = /\A(\d*(:\d*)+)([A-z]*)\z/
+
+        # Matches an instance break.  After the match:
+        #
+        #   $1:: The index string after the break.
+        #        (ex: '*' => '', '*1' => '1')
+        #
+        INSTANCE = /\A\*(\d*)\z/
+
+        # A break regexp using "[]"
+        FORK = bracket_regexp("[", "]")
+
+        # A break regexp using "{}"
+        MERGE = bracket_regexp("{", "}")
+
+        # A break regexp using "()"
+        SYNC_MERGE = bracket_regexp("(", ")")
+
+        # Parses an indicies str along commas, and collects the indicies
+        # as integers. Ex:
+        #
+        #   parse_indicies('')                  # => []
+        #   parse_indicies('1')                 # => [1]
+        #   parse_indicies('1,2,3')             # => [1,2,3]
+        #
+        def parse_indicies(str, regexp=/,+/)
+          indicies = []
+          str.split(regexp).each do |n|
+            indicies << n.to_i unless n.empty?
+          end
+          indicies
+        end
+
+        # Parses the match of a ROUND regexp into a round index
+        # and an array of task indicies that should be added to the
+        # round. The inputs correspond to $2 and $5 for the match.
+        #
+        # If $2 is nil, a round index of zero is assumed; if $5 is
+        # nil or empty, then indicies of [:current_index] are assumed.
+        #
+        #   parse_round("+", "")                # => [1, [:current_index]]
+        #   parse_round("+2", "1,2,3")          # => [2, [1,2,3]]
+        #   parse_round(nil, nil)               # => [0, [:current_index]]
+        #
+        def parse_round(two, five)
+          index = case two
+          when nil then 0
+          when /\d/ then two[1, two.length-1].to_i
+          else two.length
+          end
+          [index, five.to_s.empty? ? [current_index] : parse_indicies(five)]
+        end
+
+        # Parses the match of a SEQUENCE regexp into an [indicies, options] 
+        # array. The inputs corresponds to $1 and $3 for the match. The 
+        # previous and current index are assumed if $1 starts and/or ends 
+        # with a semi-colon.
+        #
+        #   parse_sequence("1:2:3", '')         # => [[1,2,3], {}]
+        #   parse_sequence(":1:2:", '')         # => [[:previous_index,1,2,:current_index], {}]
+        #
+        def parse_sequence(one, three)
+          seq = parse_indicies(one, /:+/)
+          seq.unshift previous_index if one[0] == ?:
+          seq << current_index if one[-1] == ?:
+          [seq, parse_options(three)]
+        end
+
+        # Parses the match of an INSTANCE regexp into an index.
+        # The input corresponds to $1 for the match. The current
+        # index is assumed if $1 is empty.
+        #
+        #   parse_instance("1")                 # => 1
+        #   parse_instance("")                  # => :current_index
+        #
+        def parse_instance(one)
+          one.empty? ? current_index : one.to_i
+        end
+
+        # Parses the match of an bracket_regexp into a [source_index,
+        # target_indicies, options] array. The inputs corresponds to $1,
+        # $2, and $3 for the match. The previous and current index are
+        # assumed if $1 and/or $2 is empty.
+        #
+        #   parse_bracket("1", "2,3", "")       # => [1, [2,3], {}]
+        #   parse_bracket("", "", "")           # => [:previous_index, [:current_index], {}]
+        #   parse_bracket("1", "", "")          # => [1, [:current_index], {}]
+        #   parse_bracket("", "2,3", "")        # => [:previous_index, [2,3], {}]
+        #
+        def parse_bracket(one, two, three)
+          targets = parse_indicies(two)
+          targets << current_index if targets.empty?
+          [one.empty? ? previous_index : one.to_i, targets, parse_options(three)]
+        end
+        
+        # Parses an options string into a hash.  The input corresponds
+        # to $3 in a SEQUENCE or bracket_regexp match.  Raises an error
+        # if the options string contains unknown options.
+        #
+        #   parse_options("")                   # => {}
+        #   parse_options("is")                 # => {:iterate => true, :stack => true}
+        #
+        def parse_options(three)
+          options = {}
+          0.upto(three.length - 1) do |char_index|
+            char = three[char_index, 1]
+            unless index = Join::SHORT_FLAGS.index(char)
+              raise "unknown option in: #{three} (#{char})"
+            end
+            
+            options[Join::FLAGS[index]] = true
+          end
+          options
+        end
+      end
+      
+      include Utils
+      
+      # The schema into which nodes are parsed
+      attr_reader :schema
+      
+      def initialize(argv=[])
+        @current_index = 0
+        @schema = Schema.new
+        parse(argv)
+      end
+
+      # Iterates through the argv splitting out task and workflow definitions.
+      # Task definitions are split out (with configurations) along round and/or
+      # workflow break lines.  Rounds and workflows are dynamically parsed;
+      # tasks may be reassigned to different rounds or workflows by later 
+      # arguments.
+      #
+      # Parse is non-destructive to argv.  If a string argv is provided, parse
+      # splits it into an array using Shellwords.
+      #
+      def parse(argv)
+        parse!(argv.kind_of?(String) ? argv : argv.dup)
+      end
+
+      # Same as parse, but removes parsed args from argv.
+      def parse!(argv)
+        argv = Shellwords.shellwords(argv) if argv.kind_of?(String)
+        argv.unshift('--')
+        
+        escape = false
+        current_argv = schema[current_index].argv        
+        
+        while !argv.empty?
+          arg = argv.shift
+
+          # if escaping, add escaped arguments 
+          # until an escape-end argument
+          if escape
+            if arg == ESCAPE_END
+              escape = false
+            else
+              current_argv << arg
+            end
+
+            next
+          end
+          
+          case arg
+          when ESCAPE_BEGIN
+            # begin escaping if indicated
+            escape = true
+            
+          when END_FLAG
+            # break on an end-flag
+            break
+          
+          when BREAK
+            # a breaking argument was reached:
+            # unless the current argv is empty,
+            # append and start a new definition
+            unless current_argv.empty?
+              self.current_index += 1
+              current_argv = schema[current_index].argv
+            end
+            
+            # parse the break string for any
+            # schema modifications
+            parse_break($1)
+            
+          else
+            # add all other non-breaking args to
+            # the current argv; this includes
+            # both inputs and configurations
+            current_argv << arg
+            
+          end
+        end
+
+        schema
+      end
+      
+      def load(argv)
+         argv.each do |arg|
+          case arg
+          when Array
+            schema.nodes << arg
+            self.current_index += 1
+          else
+            parse_break(arg)
+          end
+        end
+        
+        schema
+      end
+      
+      protected
+      
+      # The index of the node currently being parsed.
+      attr_accessor :current_index
+      
+      # Returns current_index-1, or raises an error if current_index < 1.
+      def previous_index
+        raise ArgumentError, 'there is no previous index' if current_index < 1
+        current_index - 1
+      end
+      
+      # determines the type of break and modifies self appropriately
+      def parse_break(arg) # :nodoc:
+        case arg
+        when ROUND
+          round, indicies = parse_round($2, $5)
+          indicies.each {|index| schema[index].round = round }
+          
+        when SEQUENCE
+          indicies, options = parse_sequence($1, $3)
+          while indicies.length > 1
+            schema.set(Joins::Sequence, indicies.shift, indicies[0], options)
+          end
+
+        when INSTANCE    then schema[parse_instance($1)].globalize
+        when FORK        then schema.set(Joins::Fork,       *parse_bracket($1, $2, $3))
+        when MERGE       then schema.set(Joins::Merge,      *parse_bracket($1, $2, $3))
+        when SYNC_MERGE  then schema.set(Joins::SyncMerge,  *parse_bracket($1, $2, $3))    
+        else raise ArgumentError, "invalid break argument: #{arg}"
+        end
+      end
+    end
+  end
+end