bahuvrihi-tap 0.10.7 → 0.10.8

data/lib/tap/support/constant_manifest.rb

@@ -0,0 +1,115 @@
+require 'tap/support/manifest'
+require 'tap/support/constant'
+
+module Tap
+  module Support
+    
+    # ConstantManifest builds a manifest of Constant entries using Lazydoc.
+    # The idea is that Lazydoc can find files with resouces of a specific type
+    # (ex tasks) and Constant can reference those resouces and load them as 
+    # necessary. ConstantManifest registers paths so that they may be lazily
+    # scanned when searching for a specific resource.
+    class ConstantManifest < Support::Manifest
+      
+      # The attribute identifying resources in a file
+      attr_reader :const_attr
+      
+      # Registered [root, [paths]] pairs that will be searched
+      # for the const_attr
+      attr_reader :search_paths
+      
+      # The current index of search_paths
+      attr_reader :search_path_index
+      
+      # The current index of paths
+      attr_reader :path_index
+      
+      # Initializes a new ConstantManifest
+      def initialize(const_attr)
+        @const_attr = const_attr
+        @search_paths = []
+        @search_path_index = 0
+        @path_index = 0
+        super([])
+      end
+      
+      # Registers the files matching pattern under dir.  Returns self.
+      def register(dir, pattern)
+        search_paths << [dir, Dir.glob(File.join(dir, pattern)).select {|file| File.file?(file) }]
+        self
+      end
+      
+      # Searches all paths for entries and adds them to self.  Returns self.
+      def build
+        each {|entry| } unless built?
+        self
+      end
+      
+      # True if there are no more paths to search 
+      # (ie search_path_index == search_paths.length)
+      def built?
+        search_path_index == search_paths.length
+      end
+      
+      # Sets search_path_index and path_index to zero and clears entries.
+      # Returns self.
+      def reset
+        # Support::Lazydoc[path].resolved = false
+        @entries.clear
+        @search_path_index = 0
+        @path_index = 0
+        super
+      end
+      
+      # Yields each entry to the block.  Unless built?, each lazily
+      # iterates over search_paths to look for new entries.
+      def each
+        entries.each do |entry|
+          yield(entry)
+        end
+        
+        search_paths[search_path_index, search_paths.length - search_path_index].each do |(path_root, paths)|
+          paths[path_index, paths.length - path_index].each do |path|
+            new_entries = resolve(path_root, path) - entries
+            entries.concat(new_entries)
+            
+            @path_index += 1
+            new_entries.each {|entry| yield(entry) }
+          end
+          
+          @search_path_index += 1
+          @path_index = 0
+        end unless built?
+      end
+      
+      protected
+      
+      def minikey(const) # :nodoc:
+        const.path
+      end
+      
+      # Scans path for constants having const_attr, and initializes Constant
+      # objects for each.   If the document has no default_const_name set,
+      # resolve will set the default_const_name based on the relative
+      # filepath from path_root to path.
+      def resolve(path_root, path)
+        entries = []
+        if document = Lazydoc.scan_doc(path, const_attr)
+          if document.default_const_name.empty?
+            relative_path = Root.relative_filepath(path_root, path).chomp(File.extname(path))
+            document.default_const_name = relative_path.camelize
+          end
+          
+          document.const_attrs.each_pair do |const_name, attrs|
+            if attrs.has_key?(const_attr)
+              entries << Constant.new(const_name, path)
+            end
+          end
+        end
+        
+        entries
+      end
+      
+    end
+  end
+end

data/lib/tap/support/dependencies.rb

@@ -1,89 +1,49 @@
+require 'tap/support/dependency'
+
 module Tap
   module Support
     
-    # Dependable encapsulates the module-level methods facilitating 
-    # dependencies in Executable.
-    class Dependencies
+    # Dependencies tracks Executable dependencies and results, and provides
+    # for thread-safe resolution of dependencies.
+    class Dependencies < Monitor
+      
+      # Initializes a new Dependencies
       def initialize
-        @registry = []
-        @results = []
+        super 
         @resolve_stack = []
       end
       
-      # An array of registered [instance, argv] pairs.
-      attr_reader :registry
-      
-      # An array of results matching the registry, produced 
-      # during dependency resolution by instance._execute(*argv).
-      attr_reader :results
-      
-      # Clears all registered dependencies and results.  
-      def clear
-        registry.clear
-        results.clear
-        @resolve_stack.clear
-      end
-      
-      # Returns the index of the [instance, argv] pair in self,
-      # or nil if the pair is not registered,
-      def index(instance, argv=[])
-        registry.each_with_index do |entry, index|
-          return index if entry[0] == instance && entry[1] == argv
-        end
-        nil
-      end
-      
-      # Registers an [instance, argv] pair with self and returns the index of 
-      # the pair in the registry; returns the index of a matching pair in the 
-      # registry if the instance and argv are already registered.
-      def register(instance, argv=[])
-        if existing = index(instance, argv)
-          return existing 
+      # Thread-safe registration of instance as a dependency.  During
+      # registration, instance is extended with the Dependency module.
+      # Returns self.
+      def register(instance)
+        synchronize do
+          unless instance.kind_of?(Dependency)
+            instance.extend Dependency
+          end
         end
-
-        registry << [instance, argv]
-        registry.length - 1
+        self
       end
       
-      # Resolves the instance-argv pairs at the specified indicies by calling 
-      # instance._execute(*argv).  Results are collected in results; a pair is 
-      # only resolved if an existing result does not exist and an error is
-      # raised if circular dependencies are detected. Returns self.
-      def resolve(indicies)
-        indicies.each do |index|
-          next if resolved?(index)
-          
-          if @resolve_stack.include?(index)
+      # Thread-safe resolution of the instance.  Resolve checks for
+      # circular dependencies, then yields control to the block,
+      # which is responsible for the actual resolution.
+      def resolve(instance)
+        synchronize do
+          if @resolve_stack.include?(instance)
             raise CircularDependencyError.new(@resolve_stack)
           end
-
+          
           # mark the results at the index to prevent
           # infinite loops with circular dependencies
-          @resolve_stack.push index
-
-          instance, inputs = registry[index]
-          results[index] = instance._execute(*inputs)
-          
+          @resolve_stack.push instance
+          yield()
           @resolve_stack.pop
         end
         self
       end
       
-      # Returns true if the results at the specified index are non-nil (note 
-      # that Dependable expects instance-argv pairs to resolve to an Audit; 
-      # the current value of the Audit may, of course, be nil).
-      def resolved?(index)
-        results[index] != nil
-      end
-      
-      # Sets the results at specified indicies to nil so that their 
-      # instance-argv pairs will re-execute on resolve. Returns self.
-      def reset(indicies)
-        indicies.each {|index| results[index] = nil }
-        self
-      end
-      
-      # Raised when resolve detects circular dependencies.
+      # Raised when Dependencies#resolve detects a circular dependency.
       class CircularDependencyError < StandardError
         def initialize(resolve_stack)
           super "circular dependency: [#{resolve_stack.join(', ')}]"

data/lib/tap/support/dependency.rb

@@ -0,0 +1,44 @@
+module Tap
+  module Support
+    
+    # Constrains an Executable to only _execute once, and provides several
+    # methods making the Executable behave like a Dependency.
+    module Dependency
+      
+      # The audited result of self
+      attr_accessor :_result
+      
+      def self.extended(base) # :nodoc:
+        base.instance_variable_set(:@_result, nil)
+      end
+      
+      # Conditional _execute; only calls _method_name if
+      # resolved? is false (thus assuring self will only
+      # be executed once).
+      #
+      # Returns _result.
+      def _execute(*args)
+        app.dependencies.resolve(self) do
+          @_result = super
+        end unless resolved?
+        _result
+      end
+      
+      # Alias for _execute().
+      def resolve
+        _execute
+      end
+      
+      # True if _result is non-nil.
+      def resolved?
+        @_result != nil
+      end
+      
+      # Resets the dependency by setting _result to nil.
+      def reset
+        @_result = nil
+      end
+      
+    end
+  end
+end

data/lib/tap/support/executable.rb

@@ -3,24 +3,22 @@ require 'tap/support/audit'
 module Tap
   module Support
     
-    # Executable wraps methods to make them executable by App.  Methods are 
-    # wrapped by extending the object that receives them; the easiest way
-    # to make an object executable is to use Object#_method.
+    # Executable wraps objects to make them executable by App.
     module Executable
       
-      # The Tap::App the Executable belongs to.
+      # The App receiving self during enq
       attr_reader :app
       
-      # The method called when an Executable is executed via _execute
+      # The method called during _execute
       attr_reader :_method_name
     
-      # Stores the on complete block
+      # The block called when _execute completes
       attr_reader :on_complete_block
       
-      # An array of dependency indexes that will be resolved on _execute
+      # An array of dependency indicies that will be resolved on _execute
       attr_reader :dependencies
       
-      # The batch for the Executable.
+      # The batch for self
       attr_reader :batch
       
       public
@@ -41,8 +39,8 @@ module Tap
       
       # Initializes a new batch object and adds the object to batch.
       # The object will be a duplicate of self.  (Note this method
-      # can raise an error for objects that don't support dup, like
-      # methods generated by Object#_method).
+      # can raise an error for objects that don't support dup, 
+      # notably Method objects generated by Object#_method).
       def initialize_batch_obj
         obj = self.dup
         
@@ -55,12 +53,12 @@ module Tap
       end
       
       # Returns true if the batch size is greater than one 
-      # (the one being self).  
+      # (the one is assumed to be self).  
       def batched?
         batch.length > 1
       end
 
-      # Returns the index of the self in batch.
+      # Returns the index of self in batch.
       def batch_index
         batch.index(self)
       end
@@ -125,9 +123,9 @@ module Tap
         self
       end
       
-      # Enqueues self and self.batch to app with the inputs. The number 
-      # of inputs provided should match the number of inputs specified 
-      # by the arity of the _method_name method.
+      # Enqueues each member of batch (and implicitly self) to app with the
+      # inputs. The number of inputs provided should match the number of
+      # inputs for the _method_name method.
       def enq(*inputs)
         batch.each do |executable| 
           executable.unbatched_enq(*inputs)
@@ -141,12 +139,13 @@ module Tap
         self
       end
       
-      # Sets a block to receive the results of _execute.  Raises an
-      # error if an on_complete block is already set.  Override an
-      # existing on_complete block by specifying override = true.
+      # Sets a block to receive the results of _execute for each member of 
+      # batch (and implicitly self).  Raises an error if on_complete_block
+      # is already set within the batch.  Override the existing 
+      # on_complete_block by specifying override = true.
       #
-      # Note the block recieves an audited result and not
-      # the result itself (see Audit for more information).
+      # Note: the block recieves an audited result and not the result
+      # itself (see Audit for more information).
       def on_complete(override=false, &block) # :yields: _result
         batch.each do |executable| 
           executable.unbatched_on_complete(override, &block)
@@ -154,7 +153,7 @@ module Tap
         self
       end
       
-      # Like on_complete, but only sets on_complete_block for self.
+      # Like on_complete, but only sets the on_complete_block for self.
       def unbatched_on_complete(override=false, &block) # :yields: _result
         unless on_complete_block == nil || override
           raise "on_complete_block already set: #{self}" 
@@ -163,127 +162,87 @@ module Tap
         self
       end
       
-      # Sets a sequence workflow pattern for the tasks; each task will enque 
-      # the next task with it's results.
-      #
-      # Notes:
-      # - Batched tasks will have the pattern set for each task in the batch 
-      # - The current audited results are yielded to the block, if given, 
-      #   before the next task is enqued.
-      # - Executables may provided as well as tasks.
+      # Sets a sequence workflow pattern for the tasks; each task
+      # enques the next task with it's results, starting with self.  
+      # See Joins::Sequence.
       def sequence(*tasks, &block) # :yields: _result
         Joins::Sequence.join(self, tasks, &block)
       end
 
-      # Sets a fork workflow pattern for the source task; each target
-      # will enque the results of source.
-      #
-      # Notes:
-      # - Batched tasks will have the pattern set for each task in the batch 
-      # - The current audited results are yielded to the block, if given, 
-      #   before the next task is enqued.
-      # - Executables may provided as well as tasks.
+      # Sets a fork workflow pattern for self; each target
+      # will enque the results of self.  See Joins::Fork.
       def fork(*targets, &block) # :yields: _result
         Joins::Fork.join(self, targets, &block)
       end
 
-      # Sets a simple merge workflow pattern for the source tasks. Each source
-      # enques target with it's result; no synchronization occurs, nor are 
-      # results grouped before being sent to the target.
-      #
-      # Notes:
-      # - Batched tasks will have the pattern set for each task in the batch 
-      # - The current audited results are yielded to the block, if given, 
-      #   before the next task is enqued.
-      # - Executables may provided as well as tasks.
+      # Sets a simple merge workflow pattern for the source tasks. Each 
+      # source enques self with it's result; no synchronization occurs, 
+      # nor are results grouped before being enqued.  See Joins::Merge.
       def merge(*sources, &block) # :yields: _result
         Joins::Merge.join(self, sources, &block)
       end
 
-      # Sets a synchronized merge workflow for the source tasks.  Results from
-      # each source task are collected and enqued as a single group to the target. 
-      # The target is not enqued until all sources have completed.  Raises an
-      # error if a source returns twice before the target is enqued.
-      #
-      # Notes:
-      # - Batched tasks will have the pattern set for each task in the batch 
-      # - The current audited results are yielded to the block, if given, 
-      #   before the next task is enqued.
-      # - Executables may provided as well as tasks.
-      #
-      #-- TODO: add notes on testing and the way results are received
-      # (ie as a single object)
-      # 
-      # - note stacking with a sync merge is *somewhat* pointless;
-      #   it does not change the run order, but of course it does
-      #   allow other tasks to be interleaved.
+      # Sets a synchronized merge workflow for the source tasks.  Results 
+      # from each source are collected and enqued as a single group to
+      # self.  The collective results are not enqued until all sources
+      # have completed.  See Joins::SyncMerge.
       #
+      # Raises an error if a source returns twice before the target is enqued.
       def sync_merge(*sources, &block) # :yields: _result
         Joins::SyncMerge.join(self, sources, &block)
       end
 
-      # Sets a choice workflow pattern for the source task.  When the
-      # source task completes, switch yields the audited result to the 
-      # block which then returns the index of the target to enque with 
-      # the results. No target will be enqued if the index is false or 
-      # nil; an error is raised if no target can be found for the 
-      # specified index.
-      #
-      # Notes:
-      # - Batched tasks will have the pattern set for each task in the batch 
-      # - The current audited results are yielded to the block, if given, 
-      #   before the next task is enqued.
-      # - Executables may provided as well as tasks.
+      # Sets a switch workflow pattern for self.  When _execute completes, 
+      # switch yields the audited result to the block which should return
+      # the index of the target to enque with the results. No target will 
+      # be enqued if the index is false or nil; an error is raised if no 
+      # target can be found for the specified index. See Joins::Switch.
       def switch(*targets, &block) # :yields: _result
         Joins::Switch.join(self, targets, &block)
       end
       
-      def unbatched_depends_on(dependency, *inputs)
-        raise ArgumentError, "not an Executable: #{dependency}" unless dependency.kind_of?(Executable)
-        raise ArgumentError, "cannot depend on self" if dependency == self
-        
-        index = app.dependencies.register(dependency, inputs)
-        dependencies << index unless dependencies.include?(index)
-        index
-      end
-      
-      # Adds the dependency to self, making self dependent on the dependency.
-      # The dependency will be resolved by calling dependency._execute with 
-      # the input arguments during resolve_dependencies.
-      def depends_on(dependency, *inputs)
-        index = unbatched_depends_on(dependency, *inputs)
+      # Adds the dependency to each member in batch (and implicitly self).
+      # The dependency will be resolved with the input arguments during 
+      # _execute, using resolve_dependencies.
+      def depends_on(dependency)
         batch.each do |e| 
-          e.dependencies << index unless e.dependencies.include?(index)
+          e.unbatched_depends_on(dependency)
         end
-        index
+        self
       end
       
-      # Resolves dependencies by calling dependency._execute with
-      # the dependency arguments.  (See Dependable#resolve).
+      # Like depends_on, but only adds the dependency to self.
+      def unbatched_depends_on(dependency)
+        raise ArgumentError, "cannot depend on self" if dependency == self
+        
+        app.dependencies.register(dependency)
+        dependencies << dependency unless dependencies.include?(dependency)
+        self
+      end
+      
+      # Resolves dependencies. (See Dependency#resolve).
       def resolve_dependencies
-        app.dependencies.resolve(dependencies)
+        dependencies.each {|dependency| dependency.resolve }
         self
       end
       
-      # Resets dependencies so they will be re-resolved on resolve_dependencies.
-      # (See Dependable#reset).
+      # Resets dependencies so they will be re-resolved on
+      # resolve_dependencies. (See Dependency#reset).
       def reset_dependencies
-        app.dependencies.reset(dependencies)
+        dependencies.each {|dependency| dependency.reset }
         self
       end
       
-      # Auditing method call.  Executes _method_name for self, but audits 
-      # the result. Sends the audited result to the on_complete_block if set.
+      # Auditing method call.  Resolves dependencies, executes _method_name,
+      # and sends the audited result to the on_complete_block (if set).
       #
       # Audits are initialized in the follwing manner:
-      # no inputs:: create a new, empty Audit.  The first value of the audit
-      #             will be the result of call
-      # one input:: forks the input if it is an audit, otherwise initializes
-      #             a new audit using the input
-      # multiple inputs:: merges the inputs into a new Audit.
+      # no inputs:: Creates a new, empty Audit.  The first value of the audit
+      #             will be the result of call.
+      # one input:: Forks the input if it is an audit, otherwise initializes
+      #             a new audit using the input.
+      # multiple inputs:: Merges the inputs into a new Audit.
       #
-      # Dependencies are resolved using resolve_dependencies before
-      # _method_name is executed.
       def _execute(*inputs)
         resolve_dependencies
         
@@ -317,6 +276,15 @@ module Tap
         audit
       end
       
+      # Raises a TerminateError if app.state == State::TERMINATE.
+      # check_terminate may be called at any time to provide a 
+      # breakpoint in long-running processes.
+      def check_terminate
+        if app.state == App::State::TERMINATE
+          raise App::TerminateError.new
+        end
+      end
+      
       def inspect
         "#<#{self.class.to_s}:#{object_id} _method: #{_method_name} batch_length: #{batch.length} app: #{app}>"
       end
@@ -341,10 +309,11 @@ end
 #
 class Object
   
-  # Initializes a Tap::Support::Executable using the Method returned by
-  # Object#method(method_name), setting the on_complete block as specified.  
+  # Initializes a Tap::Support::Executable using the object returned by
+  # Object#method(method_name).
+  #
   # Returns nil if Object#method returns nil.
-  def _method(method_name, app=Tap::App.instance) # :yields:  _result
+  def _method(method_name, app=Tap::App.instance)
     return nil unless m = method(method_name)
     Tap::Support::Executable.initialize(m, :call, app)
   end