bahuvrihi-tap 0.10.7 → 0.10.8

data/lib/tap/support/intern.rb

@@ -0,0 +1,46 @@
+module Tap
+  module Support
+    
+    # Generates an Intern module for the specified method_name.
+    # An Intern module:
+    # - adds an accessor for <method_name>_block
+    # - overrides <method_name> to call the block
+    # - ensures initialize_batch_obj extends the batch object
+    #   with the same Intern module
+    #
+    def self.Intern(method_name)
+      mod = INTERN_MODULES[method_name.to_sym]
+      return mod unless mod == nil
+      
+      mod = INTERN_MODULES[method_name.to_sym] = Module.new
+      mod.module_eval %Q{
+      attr_accessor :#{method_name}_block
+
+      def #{method_name}(*inputs)
+        raise "no #{method_name} block set" unless #{method_name}_block
+        inputs.unshift(self)
+      
+        arity = #{method_name}_block.arity
+        n = inputs.length
+        unless n == arity || (arity < 0 && (-1-n) <= arity) 
+          raise ArgumentError.new("wrong number of arguments (\#{n} for \#{arity})")
+        end
+      
+        #{method_name}_block.call(*inputs)
+      end
+      
+      def initialize_batch_obj(*args)
+        super(*args).extend Tap::Support::Intern(:#{method_name})
+      end
+      }
+      mod
+    end
+    
+    # An array of already-declared intern modules,
+    # keyed by method_name.
+    INTERN_MODULES = {}
+    
+    # An Intern module for :process.
+    Intern = Support.Intern(:process)
+  end
+end

data/lib/tap/support/join.rb

@@ -1,7 +1,19 @@
 module Tap
   module Support
+    
+    # Joins create on_complete blocks which link together tasks (or more
+    # generally, Executable objects) into workflows.  Joins support a 
+    # variety of configurations which affect how one task passes inputs
+    # to subsequent tasks.
+    #
+    # Joins have a single source and may have multiple targets.  See
+    # ReverseJoin for joins with a single target and multiple sources.
     class Join
       class << self
+        
+        # Create a join between the source and targets.  Targets should
+        # be an array; if the last member of targets is a hash, it will
+        # be used as the configurations for the join.
         def join(source, targets, &block)
           options = targets[-1].kind_of?(Hash) ? targets.pop : {}
           new(options).join(source, targets, &block)
@@ -10,45 +22,76 @@ module Tap
       
       include Configurable
       
+      # Causes the join to iterate the results
+      # of the source when enquing the targets.
       config :iterate, false, &c.boolean
+      
+      # Causes the targets to be enqued rather
+      # than executed immediately.
       config :stack, false, &c.boolean
+      
+      # Causes joins to only occur between the
+      # explicitly named source and targets,
+      # and not their batches.
       config :unbatched, false, &c.boolean
       
-      # An array of workflow flags.  All workflow flags are false unless specified.
+      # An array of workflow flags.  Workflow flags are false unless specified.
       FLAGS = configurations.keys
       
       # An array of the first character in each WORKFLOW_FLAGS. 
       SHORT_FLAGS = FLAGS.collect {|flag| flag.to_s[0,1]}
-
-      def initialize(options)
-        initialize_config(options)
+      
+      # Initializes a new join with the specified configuration.
+      def initialize(config)
+        initialize_config(config)
       end
       
+      # The name of the join, as a symbol.  By default 
+      # name is the basename of the underscored class.
       def name
-        self.class.to_s =~ /.*::(.*)$/
-        $1.underscore.to_sym
+        File.basename(self.class.to_s.underscore).to_sym
       end
       
+      # Creates a join between the source and targets.
+      # Must be implemented in subclasses.
+      def join(source, targets, &block)
+        raise NotImplementedError
+      end
+      
+      # A hash of the configurations set to true.
       def options
         opts = config.to_hash
         opts.delete_if {|key, value| value == false }
         opts
       end
       
+      # Returns a string like: "#<Join:object_id>"
       def inspect
         "#<Join:#{object_id}>"
       end
       
       protected
       
+      # Sets the on_complete block for the specified executable.
+      # If unbatched == true, the on_complete block will only 
+      # be set for the executable; otherwise the on_complete
+      # block will be set for executable.batch.
       def complete(executable, &block)
         executable.send(unbatched ? :unbatched_on_complete : :on_complete, &block)
       end
       
+      # Enques the executable with the results, respecting the
+      # configuration for self.
+      #
+      #                true                       false
+      #   iterate      _results are iterated      _results are enqued directly
+      #   stack        the executable is enqued   the executable is executed
+      #   unbatched    only exectuable is enqued  executable.batch is enqued
+      #
       def enq(executable, _results)
         app = executable.app
         
-        results = iterate ? _results._expand : [_results]
+        results = iterate ? _results._iterate : [_results]
         results.each do |_result|
           if stack 
       
@@ -61,10 +104,10 @@ module Tap
           else
       
             if unbatched
-              app.execute(executable, _result)
+              executable._execute(_result)
             else
               executable.batch.each do |e|
-                app.execute(e, _result)
+                e._execute(_result)
               end
             end
       
@@ -73,12 +116,25 @@ module Tap
       end
     end
     
+    # Like a Join, but with a single target and multiple sources.
     class ReverseJoin < Join
+      class << self
+        # Create a join between the sources and target.  Sources should
+        # be an array; if the last member of sources is a hash, it will
+        # be used as the configurations for the join.
+        def join(target, sources, &block)
+          options = sources[-1].kind_of?(Hash) ? sources.pop : {}
+          new(options).join(target, sources, &block)
+        end
+      end
+      
+      # Creates a join between the sources and target.
+      # Must be implemented in subclasses.
       def join(target, sources, &block)
-        options = sources[-1].kind_of?(Hash) ? sources.pop : {}
-        new(options).join(target, sources, &block)
+        raise NotImplementedError
       end
       
+      # Returns a string like: "#<ReverseJoin:object_id>"
       def inspect
         "#<ReverseJoin:#{object_id}>"
       end

data/lib/tap/support/joins.rb

@@ -2,6 +2,8 @@ require 'tap/support/join'
 
 module Tap
   module Support
+    
+    # A module of the standard Join classes supported by Tap.
     module Joins
       autoload(:Sequence, 'tap/support/joins/sequence')
       autoload(:Fork, 'tap/support/joins/fork')

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

@@ -2,6 +2,7 @@ module Tap
   module Support
     module Joins
       
+      # A Fork join passes the results of source to each of the targets.
       class Fork < Join
         def join(source, targets)
           complete(source) do |_result|

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

@@ -1,7 +1,9 @@
 module Tap
   module Support
     module Joins
-
+      
+      # Merge (or simple merge) passes the results of each source to the
+      # target without synchronization.
       class Merge < ReverseJoin
         def join(target, sources)
           sources.each do |source|

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

@@ -1,12 +1,12 @@
 module Tap
   module Support
     module Joins
-
+      
+      # A Sequence join simply pass results from one task to the next. 
       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)

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

@@ -1,7 +1,9 @@
 module Tap
   module Support
     module Joins
-
+      
+      # A Switch join allows a block to determine which target from
+      # set of targets will receive the results of the source.
       class Switch < Join
         def join(source, targets)
           complete(source) do |_result| 

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

@@ -1,7 +1,13 @@
 module Tap
   module Support
+    autoload(:Combinator, 'tap/support/combinator')
+    
     module Joins
       
+      # SyncMerge passes the collected results of the sources to the target. The
+      # results will not be passed until results from all of the sources are 
+      # available; results are passed in one group.  Similarly, a collision 
+      # results if a single source completes twice before the group.
       class SyncMerge < ReverseJoin
         def join(target, sources)
 

data/lib/tap/support/lazy_attributes.rb

@@ -2,6 +2,21 @@ require 'tap/support/lazydoc'
 
 module Tap
   module Support
+    
+    # LazyAttributes adds methods to declare class-level accessors
+    # for Lazydoc attributes.  The source_file for the class must
+    # be set manually.
+    #
+    #   # ConstName::key value
+    #   class ConstName
+    #     extend LazyAttributes
+    #
+    #     self.source_file = __FILE__
+    #     lazy_attr :key
+    #   end
+    #
+    #   ConstName::key.subject           # => 'value'
+    # 
     module LazyAttributes
       
       # The source_file for self.  Must be set independently.
@@ -21,7 +36,7 @@ module Tap
       
       private
       
-      def get_lazy_attr(attribute)
+      def get_lazy_attr(attribute) # :nodoc:
         lazydoc[self.to_s][attribute] ||= Lazydoc::Comment.new
       end
       

data/lib/tap/support/lazydoc.rb

@@ -8,9 +8,9 @@ module Tap
     # documentation, constant attributes and code comments.  To illustrate, 
     # consider the following:
     #
-    #   # Sample::key <this is the subject line>
-    #   # a constant attribute content string that
-    #   # can span multiple lines...
+    #   # Sample::key <value>
+    #   # This is the comment content.  A content
+    #   # string can span multiple lines...
     #   #
     #   #   code.is_allowed
     #   #   much.as_in RDoc
@@ -35,12 +35,12 @@ module Tap
     # Lazydoc::Comment.
     #
     #   comment = Sample::key
-    #   comment.subject       
-    #   # => "<this is the subject line>"
+    #   comment.value       
+    #   # => "<value>"
     #
     #   comment.content       
     #   # => [
-    #   # ["a constant attribute content string that", "can span multiple lines..."],
+    #   # ["This is the comment content.  A content", "string can span multiple lines..."],
     #   # [""],
     #   # ["  code.is_allowed"],
     #   # ["  much.as_in RDoc"],
@@ -50,9 +50,9 @@ module Tap
     #   "\n#{'.' * 30}\n" + comment.wrap(30) + "\n#{'.' * 30}\n"
     #   # => %q{
     #   # ..............................
-    #   # a constant attribute content
-    #   # string that can span multiple
-    #   # lines...
+    #   # This is the comment content.
+    #   # A content string can span
+    #   # multiple lines...
     #   # 
     #   #   code.is_allowed
     #   #   much.as_in RDoc
@@ -91,17 +91,17 @@ module Tap
     #   # Const::Name::k@y
     #
     # Lazydoc parses a Lazydoc::Comment for each constant attribute by using the 
-    # remainder of the line as a subject and scanning down for content.  Scanning
-    # continues until a non-comment line, an end key, or a new attribute is 
-    # reached; the comment is then stored by constant name and key.
+    # remainder of the line as a value (ie subject) and scanning down for content.
+    # Scanning continues until a non-comment line, an end key, or a new attribute
+    # is reached; the comment is then stored by constant name and key.
     #
     #   str = %Q{
-    #   # Const::Name::key subject for key
+    #   # Const::Name::key value for key
     #   # comment for key
     #   # parsed until a 
     #   # non-comment line
     #
-    #   # Const::Name::another subject for another
+    #   # Const::Name::another value for another
     #   # comment for another
     #   # parsed to an end key
     #   # Const::Name::another-
@@ -112,11 +112,11 @@ module Tap
     #   doc = Lazydoc::Document.new
     #   doc.resolve(str)
     #
-    #   doc.to_hash {|comment| [comment.subject, comment.to_s] } 
+    #   doc.to_hash {|comment| [comment.value, comment.to_s] } 
     #   # => {
     #   # 'Const::Name' => {
-    #   #   'key' =>     ['subject for key', 'comment for key parsed until a non-comment line'],
-    #   #   'another' => ['subject for another', 'comment for another parsed to an end key']}
+    #   #   'key' =>     ['value for key', 'comment for key parsed until a non-comment line'],
+    #   #   'another' => ['value for another', 'comment for another parsed to an end key']}
     #   # }
     #
     # Constant attributes are only parsed from commented lines.  To turn off
@@ -128,12 +128,12 @@ module Tap
     #   # :::-
     #   # Const::Name::not_parsed
     #   # :::+
-    #   # Const::Name::parsed subject
+    #   # Const::Name::parsed value
     #   }
     #
     #   doc = Lazydoc::Document.new
     #   doc.resolve(str)
-    #   doc.to_hash {|comment| comment.subject }   # => {'Const::Name' => {'parsed' => 'subject'}}
+    #   doc.to_hash {|comment| comment.value }   # => {'Const::Name' => {'parsed' => 'value'}}
     #
     # To hide attributes from RDoc, make use of the RDoc <tt>:startdoc:</tt> 
     # document modifier like this (note that spaces are added to prevent RDoc
@@ -173,8 +173,8 @@ module Tap
     # === Code Comments
     # Code comments are lines registered for parsing if and when a Lazydoc gets 
     # resolved. Unlike constant attributes, the registered line is the comment
-    # subject and contents are parsed up from it (basically mimicking the 
-    # behavior of RDoc).
+    # subject (ie value) and contents are parsed up from it (basically mimicking
+    # the behavior of RDoc).
     #
     #   str = %Q{
     #   # comment lines for

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

@@ -4,33 +4,32 @@ module Tap
   module Support 
     module Lazydoc
       # Comment represents a code comment parsed by Lazydoc.  Comments consist
-      # of a subject and the content of the comment which normally break down
-      # like this:
+      # of a subject and content.
       #   
       #   sample_comment = %Q{
-      #   # this is the content of the comment
+      #   # this is the content
       #   #
-      #   # which may stretch across
+      #   # content may stretch across
       #   # multiple lines
       #   this is the subject
       #   }
       #   
-      # The subject of a comment is the first non-comment line following the
-      # content, and the content is an array of comment fragments organized 
-      # by line as they would be printed in an output:
+      # Normally the subject is the first non-comment line following the content,
+      # although in some cases the subject will be manually set to something else
+      # (as in a Lazydoc constant attribute). The content is an array of comment
+      # fragments organized by line:
       #
       #   c = Comment.parse(sample_comment)
       #   c.subject      # => "this is the subject"
       #   c.content      
       #   # => [
-      #   # ["this is the content of the comment"], 
+      #   # ["this is the content"], 
       #   # [""], 
-      #   # ["which may stretch across", "multiple lines"]]
+      #   # ["content may stretch across", "multiple lines"]]
       #
-      # When pulling comments out of a document, comments may be initialized
-      # to the line of the subject and then resolved using the document:
+      # Comments may be initialized to the subject line and then resolved later:
       #
-      #   document = %Q{
+      #   doc = %Q{
       #   module Sample
       #     # this is the content of the comment
       #     # for method_one
@@ -43,26 +42,27 @@ module Tap
       #     end
       #   end}
       #
-      #   # resolve will split the document, but 
-      #   # splitting once beforehand is more efficient
-      #   lines = document.split(/\r?\n/)
-      #
-      #   c1 = Comment.new(4).resolve(lines)
+      #   c1 = Comment.new(4).resolve(doc)
       #   c1.subject     # => "  def method_one"
       #   c1.content     # => [["this is the content of the comment", "for method_one"]]
       #
-      #   c2 = Comment.new(9).resolve(lines)
+      #   c2 = Comment.new(9).resolve(doc)
       #   c2.subject     # => "  def method_two"
       #   c2.content     # => [["this is the content of the comment", "for method_two"]]
-      #   
+      # 
+      # A Regexp (or Proc) may be used in place of a line number; during resolve,
+      # the lines will be scanned and the first matching line will be used.
+      #
+      #   c3 = Comment.new(/def method_two/).resolve(doc)
+      #   c3.subject     # => "  def method_two"
+      #   c3.content     # => [["this is the content of the comment", "for method_two"]]
+      #
       class Comment
     
         class << self
       
-          # Parses the input string into a comment, stopping at end_regexp
-          # or the first non-comment line.  Also parses the next non-comment
-          # line as the comment subject.  Takes a string or a StringScanner
-          # and returns the new comment.
+          # Parses the input string into a comment.  Takes a string or a 
+          # StringScanner and returns the comment.
           #
           #   comment_string = %Q{
           #   # comments spanning multiple
@@ -73,8 +73,7 @@ module Tap
           #   #    
           #   this is the subject line
           #
-          #   # this line is not parsed as it
-          #   # is after a non-comment line
+          #   # this line is not parsed
           #   }
           #
           #   c = Comment.parse(comment_string)
@@ -137,8 +136,9 @@ module Tap
         
           # Scan determines if and how to add a line fragment to a comment and
           # yields the appropriate fragments to the block.  Returns true if
-          # fragments are yielded and false otherwise.  A comment's content 
-          # may be built from an array of lines using scan like so:
+          # fragments are yielded and false otherwise.  
+          #
+          # Content may be built from an array of lines using scan like so:
           #
           #   lines = [
           #     "# comments spanning multiple",
@@ -154,7 +154,6 @@ module Tap
           #   c = Comment.new
           #   lines.each do |line|
           #     break unless Comment.scan(line) do |fragment|
-          #       # c.unshift will also work if building in reverse
           #       c.push(fragment)  
           #     end
           #   end
@@ -197,37 +196,34 @@ module Tap
           # the appropriate objects to add the fragment to a
           # comment
           def categorize(fragment, indent) # :nodoc:
-             case
-             when fragment == indent
-               # empty comment line
-               yield [""]
-               yield []
-             when indent.empty?
-               # continuation line
-               yield fragment.rstrip
-             else 
-               # indented line
-               yield [fragment.rstrip]
-               yield []
-             end
-           end
+            case
+            when fragment == indent
+              # empty comment line
+              yield [""]
+              yield []
+            when indent.empty?
+              # continuation line
+              yield fragment.rstrip
+            else 
+              # indented line
+              yield [fragment.rstrip]
+              yield []
+            end
+          end
         end
     
-        # An array of comment fragments organized into 
-        # lines as they would be printed in an output.
-        # Ex: [["fragments", "of line", "one"], 
-        #      ["fragments", "of line", "two"]]
+        # An array of comment fragments organized into lines
         attr_reader :content
     
         # The subject of the comment (normally set to the next 
         # non-comment line after the content ends; ie the line 
-        # that would receive the comment in RDoc documentation).
+        # that would receive the comment in RDoc documentation)
         attr_accessor :subject
       
         # Returns the line number for the subject line, if known.
         # Although normally an integer, line_number may be
         # set to a Regexp or Proc to dynamically determine
-        # itself during resolve.
+        # the subject line during resolve
         attr_accessor :line_number
       
         def initialize(line_number=nil)
@@ -235,6 +231,16 @@ module Tap
           @subject = nil
           @line_number = line_number
         end
+        
+        # Alias for subject
+        def value
+          subject
+        end
+        
+        # Alias for subject=
+        def value=(value)
+          self.subject = value
+        end
 
         # Pushes the fragment onto the last line array of content.  If the
         # fragment is an array itself then it will be pushed onto content 
@@ -379,13 +385,11 @@ module Tap
         #   c.subject     # => "  def method_one"
         #   c.content     # => [["this is the content of the comment", "for method_one"]]
         #
-        # Notes:
-        # - resolve is a good hook for post-processing in subclasses
-        # - lines may be an array or a string; string inputs are split
-        #   into lines along newline boundaries.
+        # Lines may be an array or a string; string inputs are split into an
+        # array along newline boundaries.
         #
-        # === late-evaluation line numbers
-        # The line_number used by resolve may be determined directly from
+        # === dynamic line numbers
+        # The line_number used by resolve may be determined dynamically from
         # lines by setting line_number to a Regexp and Proc. In the case
         # of a Regexp, the first line matching the regexp is used:
         #
@@ -404,7 +408,7 @@ module Tap
         #   c.subject     # => "  def method_two"
         #   c.content     # => [["this is the content of the comment", "for method_two"]]
         #
-        # As shown in the examples, in both cases the late-evaluation 
+        # As shown in the examples, in both cases the dynamically determined
         # line_number overwrites the Regexp or Proc.
         def resolve(lines)
           lines = lines.split(/\r?\n/) if lines.kind_of?(String)