bahuvrihi-tap 0.10.0

data/lib/tap/support/executable_queue.rb

@@ -0,0 +1,82 @@
+module Tap
+  module Support
+    
+    # ExecutableQueue allows thread-safe enqueing and dequeing of 
+    # Executable methods and inputs for execution.  
+    class ExecutableQueue
+      include MonitorMixin
+      
+      # Creates a new ExecutableQueue
+      def initialize
+        # required for MonitorMixin
+        super()
+        @queue = []
+      end
+      
+      # Clears all methods and inputs.  Returns the existing queue as an array.
+      def clear
+        synchronize do
+          current = self.queue
+          self.queue = []
+          current
+        end
+      end
+      
+      # Returns the number of enqueued methods
+      def size
+        queue.length
+      end
+      
+      # True if no methods are enqueued
+      def empty?
+        queue.empty?
+      end
+      
+      # Enqueues the method and inputs. Raises an error if the  
+      # method is not an Executable.
+      def enq(method, inputs)
+        synchronize do
+          check_method(method)
+          queue.push [method, inputs]
+        end
+      end
+      
+      # Enqueues the method and inputs, but to the top of the queue.
+      # Raises an error if the method is not an Executable.
+      def unshift(method, inputs)
+        synchronize do
+          check_method(method)
+          queue.unshift [method, inputs]
+        end
+      end
+      
+      # Dequeues the next method and inputs as an array like
+      # [method, inputs]. Returns nil if the queue is empty.
+      def deq
+        synchronize { queue.shift }
+      end
+      
+      def concat(array)
+        synchronize do
+          array.each do |method, inputs|
+            enq(method, inputs)
+          end
+        end
+      end
+      
+      # Converts self to an array.
+      def to_a
+        queue.dup
+      end
+      
+      protected
+      
+      attr_accessor :queue
+      
+      # Checks if the input method is extended with Executable
+      def check_method(method) # :nodoc:
+        raise "not Executable: #{method}" unless method.kind_of?(Executable)
+      end
+    end 
+  end
+end

data/lib/tap/support/framework.rb

@@ -0,0 +1,71 @@
+require 'tap/support/batchable'
+require 'tap/support/executable'
+require 'tap/support/framework_class'
+
+module Tap
+  module Support
+    
+    # Framework encapsulates the basic framework functionality (batching,
+    # configuration, documentation, etc) used by Task and Workflow. Note 
+    # that Framework does NOT encapsulate the functionality needed to
+    # make a class useful in workflows, such as enq and on_complete.
+    module Framework
+      include Batchable
+      include Configurable
+    
+      def self.included(mod)
+        mod.extend Support::BatchableClass
+        mod.extend Support::ConfigurableClass
+        mod.extend Support::FrameworkClass
+      end
+    
+      # The application used to load config_file templates 
+      # (and hence, to initialize batched objects).
+      attr_reader :app
+      
+      # The name of self.
+      attr_accessor :name
+      
+      # Initializes a new instance and associated batch objects.  Batch
+      # objects will be initialized for each configuration template 
+      # specified by app.each_config_template(config_file) where 
+      # config_file = app.config_filepath(name).  
+      def initialize(config={}, name=nil, app=App.instance)
+        super()
+        @app = app
+        @name = name || self.class.default_name
+        initialize_config(config)
+      end
+      
+      # Creates a new batched object and adds the object to batch. The batched object 
+      # will be a duplicate of the current object but with a new name and/or 
+      # configurations.
+      def initialize_batch_obj(overrides={}, name=nil)
+        obj = super().reconfigure(overrides)
+        obj.name = name if name
+        obj 
+      end
+      
+      # Logs the inputs to the application logger (via app.log)
+      def log(action, msg="", level=Logger::INFO)
+        # TODO - add a task identifier?
+        app.log(action, msg, level)
+      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
+      
+      # Returns self.name
+      def to_s
+        name
+      end
+      
+    end
+  end
+end

data/lib/tap/support/framework_class.rb

@@ -0,0 +1,199 @@
+require 'tap/support/command_line'
+
+module Tap
+  module Support
+  
+    # FrameworkClass encapsulates class methods related to Framework.
+    module FrameworkClass
+       
+      # Returns the default name for the class: to_s.underscore
+      attr_accessor :default_name
+           
+      def self.extended(base)
+        caller.each_with_index do |line, index|
+          case line
+          when /\/framework.rb/ then next
+          when /^(([A-z]:)?[^:]+):(\d+)/
+            base.instance_variable_set(:@source_file, File.expand_path($1))
+            break
+          end
+        end
+        
+        base.instance_variable_set(:@default_name, base.to_s.underscore)
+      end
+      
+      def inherited(child)
+        unless child.instance_variable_defined?(:@source_file)
+          caller.first =~ /^(([A-z]:)?[^:]+):(\d+)/
+          child.instance_variable_set(:@source_file, File.expand_path($1)) 
+        end
+        
+        child.instance_variable_set(:@default_name, child.to_s.underscore)
+        super
+      end
+
+      def subclass(const_name, configs={}, options={}, &block)
+        # Generate the nesting module
+        current, constants = const_name.to_s.constants_split
+        raise ArgumentError, "#{current} is already defined!" if constants.empty?
+         
+        subclass_const = constants.pop
+        constants.each {|const| current = current.const_set(const, Module.new)}
+        
+        # Generate the subclass
+        subclass = Class.new(self)
+        configs = configs[0] if configs.kind_of?(Array) && configs.length == 1 && configs[0].kind_of?(Hash)
+        
+        case configs
+        when Hash
+          subclass.send(:attr_accessor, *configs.keys)
+          configs.each_pair do |key, value|
+            subclass.configurations.add(key, value)
+          end
+        when Array
+          configs.each do |method, key, value, opts, config_block| 
+            subclass.send(method, key, value, opts, &config_block)
+          end
+        end
+        
+        block_method = options[:block_method] || :process
+        subclass.send(:define_method, block_method, &block)
+        subclass.default_name = const_name
+
+        const_name = current == Object ? subclass_const : "#{current}::#{subclass_const}"
+        caller.each_with_index do |line, index|
+          case line
+          when /\/tap\/support\/declarations.rb/ then next
+          when /^(([A-z]:)?[^:]+):(\d+)/
+            subclass.source_file = File.expand_path($1)
+            subclass.lazydoc[const_name, false]['manifest'] = subclass.lazydoc.register($3.to_i - 1)
+            break
+          end
+        end
+        
+        arity = options[:arity] || block.arity
+        comment = Comment.new
+        comment.subject = case
+        when arity > 0
+          Array.new(arity, "INPUT").join(' ')
+        when arity < 0
+          array = Array.new(-1 * arity - 1, "INPUT")
+          array << "INPUTS..."
+          array.join(' ')
+        else ""
+        end
+        subclass.lazydoc[const_name, false]['args'] ||= comment
+        
+        # Set the subclass constant
+        current.const_set(subclass_const, subclass)
+      end
+      
+      DEFAULT_HELP_TEMPLATE = %Q{<%= task_class %><%= manifest.subject.to_s.strip.empty? ? '' : ' -- ' %><%= manifest.subject %>
+
+<% unless manifest.empty? %>
+<%= '-' * 80 %>
+
+<% manifest.wrap(77, 2, nil).each do |line| %>
+  <%= line %>
+<% end %>
+<%= '-' * 80 %>
+<% end %>
+
+}
+
+      def instantiate(argv, app=Tap::App.instance) # => instance, argv
+        opts = OptionParser.new
+ 
+        # Add configurations
+        config = {}
+        unless configurations.empty?
+          opts.separator ""
+          opts.separator "configurations:"
+        end
+
+        configurations.each do |receiver, key, configuration|
+          opts.on(*CommandLine.configv(configuration)) do |value|
+            config[key] = value
+          end
+        end
+
+        # Add options on_tail, giving priority to configurations
+        opts.separator ""
+        opts.separator "options:"
+
+        opts.on_tail("-h", "--help", "Print this help") do
+          args = lazydoc(true)[to_s]['args'] || Tap::Support::Comment.new
+
+          opts.banner = "#{help}usage: tap run -- #{to_s.underscore} #{args.subject}"
+          puts opts
+          exit
+        end
+
+        # Add option for name
+        name = default_name
+        opts.on_tail('--name NAME', /^[^-].*/, 'Specify a name') do |value|
+          name = value
+        end
+
+        # Add option to add args
+        use_args = []
+        opts.on_tail('--use FILE', /^[^-].*/, 'Loads inputs from file') do |value|
+          obj = YAML.load_file(value)
+          case obj
+          when Hash 
+            obj.values.each do |array|
+              # error if value isn't an array
+              use_args.concat(array)
+            end
+          when Array 
+            use_args.concat(obj)
+          else
+            use_args << obj
+          end
+        end
+
+        opts.parse!(argv)
+        obj = new({}, name, app)
+
+        path_configs = load_config(app.config_filepath(name))
+        if path_configs.kind_of?(Array)
+          path_configs.each_with_index do |path_config, i|
+            obj.initialize_batch_obj(path_config, "#{name}_#{i}") unless i == 0
+          end
+          path_configs = path_configs[0]
+        end
+
+        [obj.reconfigure(path_configs).reconfigure(config), argv + use_args]
+      end
+      
+      def lazydoc(resolve=false, args_method=:process)
+        if resolve
+          lazydoc = super(false)
+          lazydoc.resolve(nil, /^\s*def\s+#{args_method}(\((.*?)\))?/) do |comment, match|
+            comment.subject = match[2].to_s.split(',').collect do |arg|
+              arg = arg.strip.upcase
+              case arg
+              when /^&/ then nil
+              when /^\*/ then arg[1..-1] + "..."
+              else arg
+              end
+            end.join(', ')
+
+            lazydoc.default_attributes['args'] ||= comment
+          end
+          
+          super(true)
+        else       
+          super(false)
+        end
+      end
+      
+      def help
+        Tap::Support::Templater.new(DEFAULT_HELP_TEMPLATE, 
+          :task_class => self, 
+          :manifest => lazydoc(true)[to_s]['manifest'] || Tap::Support::Comment.new
+        ).build
+      end
+    end
+  end
+end

data/lib/tap/support/instance_configuration.rb

@@ -0,0 +1,147 @@
+module Tap
+  module Support
+    
+    # InstanceConfiguration serves as a forwarding hash, where get and set operations
+    # for configurations are sent to instance methods rather than to an underlying data 
+    # store.  
+    #
+    #   class Sample
+    #     attr_accessor :key
+    #   end
+    #   sample = Sample.new
+    #
+    #   class_config = ClassConfiguration.new(Sample)
+    #   class_config.add(:key)
+    #
+    #   config = InstanceConfiguration.new(class_config)
+    #   config.bind(sample)
+    #
+    #   sample.key = 'value'
+    #   config[:key]                # => 'value'
+    #
+    #   config[:key] = 'another'
+    #   sample.key                  # => 'another'
+    #
+    # Non-config keys are simply stored:
+    #
+    #   config[:not_a_key] = 'value'
+    #   config[:not_a_key]          # => 'value'
+    #
+    #   config.store                # => {:not_a_key => 'value'}
+    #   config.to_hash              # => {:key => 'another', :not_a_key => 'value'}
+    #
+    class InstanceConfiguration
+      
+      # The bound receiver
+      attr_reader :receiver
+      
+      # The underlying data store for non-config keys
+      attr_reader :store
+      
+      # The ClassConfiguration specifying config keys
+      attr_reader :class_config
+      
+      def initialize(class_config, receiver=nil)
+        @receiver = receiver
+        @store = {}
+        @class_config = class_config
+      end
+      
+      # Binds self to the specified receiver.  Mapped keys are
+      # removed from store and sent to their writer method on 
+      # receiver.
+      def bind(receiver)
+        raise ArgumentError.new("receiver cannot be nil") if receiver == nil
+        
+        class_config.each_pair do |key, config|
+          receiver.send(config.writer, store.delete(key))
+        end
+        @receiver = receiver
+        
+        self
+      end
+      
+      # Returns true if self is bound to a receiver
+      def bound?
+        receiver != nil
+      end
+      
+      # Unbinds self from the specified receiver.  Mapped values
+      # are stored in store.  Returns the unbound receiver.
+      def unbind
+        class_config.each_pair do |key, config|
+          store[key] = receiver.send(config.reader)
+        end
+        r = receiver
+        @receiver = nil
+        
+        r
+      end
+      
+      # Duplicates self, returning an unbound InstanceConfiguration.
+      def dup
+        duplicate = super()
+        duplicate.instance_variable_set(:@receiver, nil)
+        duplicate.instance_variable_set(:@store, @store.dup)
+        duplicate
+      end
+      
+      # Associates the value the key.  If bound? and the key
+      # is a class_config key, then the value will be forwarded
+      # to the class_config.writer method on the receiver.
+      def []=(key, value)
+        case 
+        when bound? && config = class_config.map[key.to_sym]
+          receiver.send(config.writer, value)
+        else store[key] = value
+        end
+      end
+      
+      # Retrieves the value corresponding to the key. If bound? 
+      # and the key is a class_config key, then the value is
+      # obtained from the :key method on the receiver.
+      def [](key)
+        case 
+        when bound? && config = class_config.map[key.to_sym]
+          receiver.send(config.reader)
+        else store[key]
+        end
+      end
+      
+      # True if the key is assigned in self.
+      def has_key?(key)
+        (bound? && class_config.key?(key)) || store.has_key?(key) 
+      end
+      
+      # Calls block once for each key-value pair stored in self.
+      def each_pair # :yields: key, value
+        class_config.each_pair do |key, config|
+          yield(key, receiver.send(config.reader))
+        end if bound?
+        
+        store.each_pair do |key, value|
+          yield(key, value)
+        end
+      end
+      
+      # Equal if the to_hash values of self and another are equal.
+      def ==(another)
+        to_hash == another.to_hash
+      end
+      
+      # Returns self as a hash. 
+      def to_hash
+        hash = store.dup
+        class_config.keys.each do |key|
+          hash[key] = self[key]
+        end if bound?
+        hash
+      end
+      
+      # Overrides default inspect to show the to_hash values.
+      def inspect
+        "#<#{self.class}:#{object_id} to_hash=#{to_hash.inspect}>"
+      end
+    end
+  end
+end