tap 0.9.1 → 0.10.0

data/lib/tap/support/configuration.rb

@@ -0,0 +1,122 @@
+module Tap
+  module Support
+    class Configuration
+      class << self
+        SHORT_REGEXP = /^-[A-z]$/
+        
+        # Turns the input string into a short-format option.  Raises
+        # an error if the option does not match SHORT_REGEXP.
+        #
+        #   Configuration.shortify("-o")   # => '-o'
+        #   Configuration.shortify(:o)     # => '-o'
+        #
+        def shortify(str)
+          str = str.to_s
+          str = "-#{str}" unless str[0] == ?-
+          raise "invalid short option: #{str}" unless str =~ SHORT_REGEXP
+          str
+        end
+
+        LONG_REGEXP = /^--(\[no-\])?([A-z][\w-]*)$/
+        
+        # Turns the input string into a long-format option.  Raises
+        # an error if the option does not match LONG_REGEXP.
+        #
+        #   Configuration.longify("--opt")                     # => '--opt'
+        #   Configuration.longify(:opt)                        # => '--opt'
+        #   Configuration.longify(:opt, true)                  # => '--[no-]opt'
+        #   Configuration.longify(:opt_ion)                    # => '--opt-ion'
+        #   Configuration.longify(:opt_ion, false, false)      # => '--opt_ion'
+        #
+        def longify(str, switch_notation=false, hyphenize=true)
+          str = str.to_s
+          str = "--#{str}" unless str.index("--")
+          str.gsub!(/_/, '-') if hyphenize
+          
+          raise "invalid long option: #{str}" unless str =~ LONG_REGEXP
+          
+          if switch_notation && $1.nil?
+            str = "--[no-]#{$2}"
+          end
+
+          str
+        end
+      end
+      
+      attr_reader :name
+      attr_reader :reader
+      attr_reader :writer
+      attr_reader :duplicable
+      attr_reader :attributes
+ 
+      def initialize(name, default=nil, options={})
+        @name = name
+        self.default = default
+        
+        self.reader = options.delete(:reader) || name
+        self.writer = options.delete(:writer) || "#{name}="
+        @attributes = options
+      end
+
+      # Sets the default value for self and determines if the
+      # default is duplicable (ie not nil, true, false, Symbol, 
+      # Numeric, and responds_to?(:dup)).
+      def default=(value)
+        @duplicable = case value
+        when nil, true, false, Symbol, Numeric then false
+        else value.respond_to?(:dup)
+        end
+        
+        @default = value.freeze
+      end
+      
+      # Returns the default value, or a duplicate of the default
+      # value if specified and the default value is duplicable.
+      def default(duplicate=true)
+        duplicate && duplicable ? @default.dup : @default
+      end
+      
+      # Sets the reader for self.  The reader is symbolized.
+      def reader=(value)
+        @reader = value.to_sym
+      end
+      
+      # Sets the writer for self.  The writer is symbolized.
+      def writer=(value)
+        @writer = value.to_sym
+      end
+      
+      def arg_name
+        attributes[:arg_name] || name.to_s.upcase
+      end
+      
+      def arg_type
+        attributes[:arg_type] || :mandatory
+      end
+      
+      def long(switch_notation=false, hyphenize=true)
+        Configuration.longify(attributes[:long] || name.to_s, switch_notation, hyphenize)
+      end
+      
+      def short
+        attributes[:short] ? Configuration.shortify(attributes[:short]) : nil
+      end
+      
+      def desc
+        attributes[:desc]
+      end
+
+      # True if another is a kind of Configuration with the same name,
+      # default value, reader and writer; other attributes are NOT 
+      # taken into account.
+      def ==(another)
+        another.kind_of?(Configuration) && 
+        self.name == another.name &&
+        self.reader == another.reader &&
+        self.writer == another.writer &&
+        self.default(false) == another.default(false)
+      end
+      
+    end
+  end
+end

data/lib/tap/support/constant.rb

@@ -0,0 +1,70 @@
+require 'tap/support/constant_utils'
+class String # :nodoc:
+  include Tap::Support::ConstantUtils
+end
+
+module Tap
+  module Support
+    class Constant
+      
+      # The camelized name for self.
+      attr_reader :name
+      
+      # The path to load to initialize the constant name.
+      attr_reader :require_path
+  
+      def initialize(name, require_path=nil)
+        @name = name
+        @require_path = require_path
+      end
+      
+      # Returns the underscored name.
+      def path
+        @path ||= name.underscore
+      end
+      
+      # Returns the basename of path.
+      def basename
+        @basename ||= File.basename(path)
+      end
+      
+      # Returns the path, minus the basename of path. 
+      def dirname
+        @dirname ||= (dirname = File.dirname(path)) == "." ? "" : dirname
+      end
+      
+      # Returns the name of the constant, minus nesting.
+      def const_name
+        @const_name ||= (name =~ /.*::(.*)$/ ? $1 : name)
+      end
+      
+      # Returns an array of the nesting constants of name.
+      def nesting
+        @nesting ||= (name =~ /(.*)::.*$/ ? $1 : '')
+      end
+      
+      # Returns the number of constants in nesting.
+      def nesting_depth
+        @nesting_depth ||= nesting.split(/::/).length
+      end
+  
+      # Returns the document for require_path, if set, or nil otherwise.
+      def document
+        require_path ? Support::Lazydoc[require_path] : nil 
+      end
+      
+      def ==(another)
+        another.kind_of?(Constant) && 
+        another.name == self.name &&
+        another.require_path == self.require_path
+      end
+  
+      def constantize
+        name.try_constantize do |const_name|
+          require require_path
+          name.constantize
+        end
+      end
+    end
+  end
+end

data/lib/tap/support/constant_utils.rb

@@ -0,0 +1,127 @@
+module Tap
+  module Support
+    
+    # ConstantUtils provides methods for transforming strings into constants.
+    # Several methods are directly taken from or based heavily on the
+    # ActiveSupport {Inflections}[http://api.rubyonrails.org/classes/ActiveSupport/CoreExtensions/String/Inflections.html]
+    # module and 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 ConstantUtils
+      
+      # 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
+      
+      # constantize tries to find a declared constant with the name specified 
+      # by self. It raises a NameError when the name is not in CamelCase 
+      # or is not initialized.  
+      def constantize
+        case RUBY_VERSION
+        when /^1.9/
+
+          # a check is necessary to maintain the 1.8 behavior  
+          # in 1.9, where ancestor constants may be returned 
+          # by a direct evaluation
+          const_name.split("::").inject(Object) do |current, const|
+            const = const.to_sym
+
+            current.const_get(const).tap do |c|
+              unless current.const_defined?(const, false)
+                raise NameError.new("uninitialized constant #{const_name}") 
+              end
+            end
+          end
+
+        else 
+          Object.module_eval("::#{const_name}", __FILE__, __LINE__)
+        end
+      end
+      
+      # Tries to constantize self; if a NameError is raised, try_constantize
+      # passes control to the block.  Control is only passed if the NameError
+      # is for one of the constants in self.
+      def try_constantize
+        begin
+          constantize  
+        rescue(NameError)
+          error_name = $!.name.to_s 
+          missing_const = const_name.split(/::/).inject(Object) do |current, const|
+            if current.const_defined?(const) 
+              current.const_get(const) 
+            else 
+              break(const)
+            end
+          end
+
+          # check that the error_name is the first missing constant
+          raise $! unless missing_const == error_name
+          yield(const_name)
+        end
+      end
+      
+      def constants_split
+        camel_cased_word = camelize
+        unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ camel_cased_word
+          raise NameError, "#{camel_cased_word.inspect} is not a valid constant name!"
+        end
+
+        constants = $1.split(/::/)
+        current = Object
+        while !constants.empty?
+          break unless current.const_defined?(constants[0])
+          current = current.const_get(constants.shift)
+        end
+
+        [current, constants]
+      end
+
+      protected
+
+      def const_name
+        unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ self
+          raise NameError, "#{inspect} is not a valid constant name!"
+        end
+        $1
+      end
+      
+    end
+  end
+end

data/lib/tap/support/declarations.rb

@@ -0,0 +1,111 @@
+module Tap
+  module Support
+    module Declarations
+      def self.set_declaration_base(base)
+        # TODO -- warn if base is Object -- conflict with Rake
+        declaration_base = base.to_s
+        declaration_base = "" if ["Object", "Tap"].include?(declaration_base)
+
+        base.instance_variable_set(:@tap_declaration_base, declaration_base.underscore)
+      end
+
+      def self.included(base)
+        set_declaration_base(base)
+      end
+
+      def self.extended(base)
+        set_declaration_base(base)
+      end
+
+      def tasc(name, configs={}, options={}, &block)
+        Tap::Task.subclass(nest(name), configs, options, &block)
+      end
+
+      def task(name, configs={}, options={}, &block)
+        options[:arity] = arity(block)
+        tasc(name, configs, options, &task_block(block)).new
+      end
+
+      def file_tasc(name, configs={}, options={}, &block)
+        Tap::FileTask.subclass(nest(name), configs, options, &block)
+      end
+
+      def file_task(name, configs={}, options={}, &block)
+        options[:arity] = arity(block)
+        file_tasc(nest(name), configs, options, &task_block(block)).new
+      end
+
+      def worcflow(name, configs={}, options={}, &block)
+        Tap::Workflow.subclass(nest(name), configs, options, &block)
+      end
+
+      def workflow(name, configs={}, options={}, &block)
+        options[:arity] = arity(block)
+        worcflow(name, configs, options, &task_block(block)).new
+      end
+
+      protected
+
+      def config(key, value=nil, options={}, &block)
+        caller.each_with_index do |line, index|
+          case line
+          when /^(([A-z]:)?[^:]+):(\d+)/
+            options[:desc] = Support::Lazydoc.register($1, $3.to_i - 1)
+            break
+          end
+        end if options[:desc] == nil
+
+        [:config, key, value, options, block]
+      end
+
+      def config_attr(key, value=nil, options={}, &block)
+        caller.each_with_index do |line, index|
+          case line
+          when /^(([A-z]:)?[^:]+):(\d+)/
+            options[:desc] = Support::Lazydoc.register($1, $3.to_i - 1)
+            break
+          end
+        end if options[:desc] == nil
+
+        [:config_attr, key, value, options, block]
+      end
+
+      def c
+        Support::Validation
+      end
+
+      private
+
+      def nest(name)
+        # use self if self is a Module or Class, 
+        # or self.class if self is an instance.
+        File.join((self.kind_of?(Module) ? self : self.class).instance_variable_get(:@tap_declaration_base), name.to_s)
+      end
+      
+      def arity(block)
+        arity = block.arity
+        
+        case
+        when arity > 0 then arity -= 1
+        when arity < 0 then arity += 1
+        end
+        
+        arity
+      end
+
+      def task_block(block)
+        lambda do |*inputs|
+          inputs.unshift(self)
+
+          arity = block.arity
+          n = inputs.length
+          unless n == arity || (arity < 0 && (-1-n) <= arity) 
+            raise ArgumentError.new("wrong number of arguments (#{n} for #{arity})")
+          end
+
+          block.call(*inputs)
+        end
+      end
+    end
+  end
+end

data/lib/tap/support/executable.rb

@@ -1,23 +1,25 @@
+require 'tap/support/audit'
+
 module Tap
   module Support
-    # Executable wraps methods to make them executable by App.
+    # 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.
     module Executable
       
       # The method called when an Executable is executed via _execute
       attr_reader :_method_name
     
-      # Indicates whether or not to call in multithread mode.  Default false.
+      # Indicates whether or not to execute in multithread mode.
       attr_accessor :multithread
 
-      # Stores the on complete block.  Default is Executable.default_on_complete_block.
+      # Stores the on complete block.
       attr_reader :on_complete_block
     
-      protected
-      
-      attr_writer :_method_name
-    
       public
-
+      
+      # Extends obj with Executable and sets up all required variables.  The
+      # specified method will be called on _execute.
       def self.initialize(obj, method_name, multithread=false, &on_complete_block)
         obj.extend Executable
         obj.instance_variable_set(:@_method_name, method_name)
@@ -26,8 +28,9 @@ module Tap
         obj
       end
     
-      # Sets a block to receive the results of _call.  Raises an error 
-      # if on_complete_block is already set, unless override = true.
+      # 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.
       #
       # Note the block recieves an audited result and not
       # the result itself (see Audit for more information).
@@ -82,15 +85,25 @@ module Tap
   end
 end
 
-# Tap extends Object with a convenience method to generate methods
-# that can be enqued by App and incorporated into workflows.  
+# Tap extends Object with <tt>_method</tt> to generate executable methods
+# that can be enqued by Tap::App and incorporated into workflows.
+#
+#   array = []
+#   push_to_array = array._method(:push)
+#
+#   task = Tap::Task.new  
+#   task.app.sequence(task, push_to_array)
+#
+#   task.enq(1).enq(2,3)
+#   task.app.run
+#
+#   array   # => [[1],[2,3]]
+#
 class Object
   
-  # Makes a Tap::Support::Executable for the Method returned by
-  # Object#method, setting multithread and the on_complete block 
-  # as specified.  The method will be called on _execute.
-  #
-  # Returns nil if Object#method returns nil.
+  # Initializes a Tap::Support::Executable using the Method returned by
+  # Object#method(method_name), setting multithread and the on_complete 
+  # block as specified.  Returns nil if Object#method returns nil.
   def _method(method_name, multithread=false, &on_complete_block) # :yields:  _result
     return nil unless m = method(method_name)
     Tap::Support::Executable.initialize(m, :call, multithread, &on_complete_block)