tap 0.9.1 → 0.10.0

data/lib/tap/support/templater.rb

@@ -0,0 +1,180 @@
+require 'ostruct'
+require 'erb'
+
+module Tap
+  module Support
+    
+    # Templater is a convenience class for creating ERB templates.  As
+    # an OpenStruct, attributes can be assigned/unassigned at will to
+    # a Templater.  When the template is built, all the method of 
+    # Templater (and hence all the assigned attributes) are available
+    # in the template.
+    #
+    #   t = Templater.new( "key: <%= value %>")
+    #   t.value = "default"
+    #   t.build                 # => "key: default"
+    #
+    #   t.value = "another"
+    #   t.build                 # => "key: another"
+    #
+    # Templater includes the Templater::Utils utility methods.
+    #
+    # === ERB Redirection
+    #
+    # Templater hooks into the ERB templating mechanism by providing itself 
+    # as the ERB output target (_erbout).  ERB concatenates each line of an 
+    # ERB template to _erbout, as can be seen when you look at the src code 
+    # evaluated by ERB:
+    #
+    #   e = ERB.new("<%= 1 + 2 %>")
+    #   e.src                   # => "_erbout = ''; _erbout.concat(( 1 + 2 ).to_s); _erbout"
+    #
+    # By setting itself as _erbout, instances of Templater can redirect the 
+    # output to a temporary target which can then be used in string 
+    # transformations.  For example, redirection allows indentation of 
+    # nested content:
+    #
+    #   template = %Q{
+    #   # Un-nested content
+    #   <% redirect do |target| %>
+    #   # Nested content
+    #   <% module_nest("Nesting::Module") { target } %>
+    #   <% end %>
+    #   }
+    #
+    #   t = Templater.new(template)
+    #   t.build
+    #   # => %Q{
+    #   # # Un-nested content
+    #   # module Nesting
+    #   #   module Module
+    #   #     # Nested content
+    #   #     
+    #   #   end
+    #   # end}
+    #
+    class Templater < OpenStruct
+      
+      # Utility methods for Templater; mostly string manipulations
+      # useful in creating documentation.
+      module Utils
+        
+        # yamlize converts the object to YAML (using to_yaml), omitting
+        # the header and final newline:
+        #
+      	#   {'key' => 'value'}.to_yaml           # => "--- \nkey: value\n"
+      	#   yamlize {'key' => 'value'}           # => "key: value"
+        def yamlize(object)
+        	object.to_yaml[5...-1]
+        end
+        
+        # Nest the return of the block in the nesting lines.
+        #
+        #  nest([["\nmodule Some", "end\n"],["module Nested", "end"]]) { "class Const\nend" }
+        #  # => %Q{
+        #  # module Some
+        #  #   module Nested
+        #  #     class Const
+        #  #     end
+        #  #   end
+        #  # end
+        #  # }
+        #
+        def nest(nesting, indent="  ", line_sep="\n")
+          content = yield
+          return content if nesting.empty?
+          
+          depth = nesting.length
+          lines = [indent * depth + content.gsub(/#{line_sep}/, line_sep + indent * depth)]
+
+          nesting.reverse_each do |(start_line, end_line)|
+            depth -= 1
+            lines.unshift(indent * depth + start_line)
+            lines << (indent * depth + end_line)
+          end
+
+          lines.join(line_sep)
+        end
+        
+        # Nest the return of the block in the nesting module.
+        #
+        #  module_nest('Some::Nested') { "class Const\nend" }
+        #  # => %Q{
+        #  # module Some
+        #  #   module Nested
+        #  #     class Const
+        #  #     end
+        #  #   end
+        #  # end
+        #  # }.strip
+        #
+        def module_nest(const_name, indent="  ", line_sep="\n")
+          nesting = const_name.split(/::/).collect do |name|
+            ["module #{name}", "end"]
+          end
+          
+          nest(nesting, indent, line_sep) { yield }
+        end
+      end
+      
+      include Utils
+      
+      # Initialized a new Templater.  An ERB or String may be provided as the
+      # template.  If a String is provided, it will be used to initialize an
+      # ERB with a trim_mode of "<>".
+      def initialize(template, attributes={})
+        @template = case template
+        when ERB 
+          if template.instance_variable_get(:@src).index('_erbout =') != 0
+            raise ArgumentError, "Templater does not work with ERB templates where eoutvar != '_erbout'"
+          end
+          template
+        when String then ERB.new(template, nil, "<>")
+        else raise ArgumentError, "cannot convert #{template.class} into an ERB template"
+        end
+        
+        src = @template.instance_variable_get(:@src)
+        @template.instance_variable_set(:@src, "self." + src) 
+
+        super(attributes)
+      end
+      
+      # Returns self (not the underlying erbout storage that actually receives 
+      # the output lines).  In the ERB context, this method directs erb outputs
+      # to Templater#concat and into the redirect mechanism.
+      def _erbout
+        self
+      end
+      
+      # Sets the underlying erbout storage to input.
+      def _erbout=(input)
+        @_erbout = input
+      end
+      
+      # Redirects output of erb to the redirected_erbout string
+      # for the duration of the block.  When redirect completes,
+      # the redirected_erbout is concatenated to the main
+      # erbout storage.
+      def redirect # :yields: redirected_erbout
+        current = @_erbout
+        @_erbout = ""
+        result = yield(@_erbout)
+        @_erbout = current
+        concat(result)
+      end
+      
+      # Concatenates the specified input to the underlying erbout storage.
+      def concat(input)
+        @_erbout << input
+      end
+      
+      # Build the template.  All methods of self will be 
+      # accessible in the template.
+      def build
+        @template.result(binding)
+        @_erbout
+      end
+      
+    end
+  end
+end

data/lib/tap/support/validation.rb

@@ -1,77 +1,410 @@
-autoload(:PP, 'pp')
-
-module Tap
-  module Support
-    
-    # Validation generates blocks for common validations/processing of 
-    # configurations set through Configurable.  These blocks can be passed
-    # to the config declarations using an ampersand (&).
-    #
-    # See the 'Configuration' section in the Tap::Task documentation for
-    # more details on how Validation works in practice.
-    module Validation
-      
-      # Raised when Validation blocks fail.
-      class ValidationError < ArgumentError
-        def initialize(input, validations)
-          validation_str = PP.singleline_pp(validations, "")
-          super PP.singleline_pp(input, "expected #{validation_str} but was: ")
-        end
-      end
-      
-      module_function
-      
-      # Yaml conversion and checker.  Valid if any of the validations
-      # match in a case statement.  Otherwise raises an error.
-      
-      # Returns input if any of the validations match the input, as
-      # in a case statement.  Raises a ValidationError otherwise.
-      #
-      # For example:
-      #
-      #   validate(10, [Integer, nil])
-      #
-      # Does the same as:
-      #
-      #   case 10
-      #   when Integer, nil then input
-      #   else raise ValidationError.new(...)
-      #   end
-      #
-      def validate(input, validations)
-        case input
-        when *validations then input
-        else
-          raise ValidationError.new(input, validations)
-        end
-      end
-      
-      # Returns a block that calls validate using the block input
-      # and the input validations.
-      def check(*validations)
-        lambda {|input| validate(input, validations) }
-      end
-    
-      # Returns a block that loads input strings as YAML, then
-      # calls validate with the result and the input validations.
-      # If the block input is not a string, the block input is 
-      # validated.
-      #
-      #   b = yaml(Integer, nil)
-      #   b.class                 # => Proc
-      #   b.call(1)               # => 1
-      #   b.call("1")             # => 1
-      #   b.call(nil)             # => nil
-      #   b.call("str")           # => ValidationError
-      #
-      # Note: yaml is especially useful for validating configs
-      # that may be specified as strings or as an actual object.
-      def yaml(*validations)
-        lambda do |input|
-          res = input.kind_of?(String) ? YAML.load(input) : input
-          validate(res, validations)
-        end
-      end
-    end
-  end
+module Tap
+  module Support
+    
+    # Validation generates blocks for common validations and transformations of 
+    # configurations set through Configurable.  In general these blocks allow
+    # configurations to be set to objects of a particular class, or to a string
+    # that can be loaded as YAML into such an object.
+    #
+    #   integer = Validation.integer
+    #   integer.class             # => Proc
+    #   integer.call(1)           # => 1
+    #   integer.call('1')         # => 1
+    #   integer.call(nil)         # => ValidationError
+    #
+    #--
+    # Note the unusual syntax for declaring constants that are blocks
+    # defined by lambda... ex:
+    #
+    #   block = lambda {}
+    #   CONST = block
+    #
+    # This syntax plays well with RDoc, which otherwise gets jacked 
+    # when you do it all in one step.
+    #++
+    module Validation
+      
+      # Raised when Validation blocks fail.
+      class ValidationError < ArgumentError
+        def initialize(input, validations)
+          super case 
+          when validations.empty?
+            "no validations specified"
+          else 
+            validation_str = PP.singleline_pp(validations, "")
+            PP.singleline_pp(input, "expected #{validation_str} but was: ")
+          end
+        end
+      end
+      
+      # Raised when yamlization fails.
+      class YamlizationError < ArgumentError
+        def initialize(input, error)
+          super "#{error} ('#{input}')"
+        end
+      end
+      
+      module_function
+      
+      # Yaml conversion and checker.  Valid if any of the validations
+      # match in a case statement.  Otherwise raises an error.
+      
+      # Returns input if any of the validations match any of the
+      # inputs, as in a case statement.  Raises a ValidationError 
+      # otherwise.  For example:
+      #
+      #   validate(10, [Integer, nil])
+      #
+      # Does the same as:
+      #
+      #   case 10
+      #   when Integer, nil then input
+      #   else raise ValidationError.new(...)
+      #   end
+      #
+      # Note the validations input must be an Array or nil; 
+      # validate will raise an ArgumentError otherwise.  
+      # All inputs are considered VALID if validations == nil.
+      def validate(input, validations)
+        case validations
+        when Array
+        
+          case input
+          when *validations then input
+          else raise ValidationError.new(input, validations)
+          end
+          
+        when nil then input
+        else raise ArgumentError.new("validations must be nil, or an array of valid inputs")
+        end
+      end
+      
+      # Attempts to load the input as YAML.  Raises a YamlizationError
+      # for errors.
+      def yamlize(input)
+        begin
+          YAML.load(input)
+        rescue
+          raise YamlizationError.new(input, $!.message)
+        end
+      end
+      
+      # Returns a block that calls validate using the block input
+      # and the input validations.  Raises an error if no validations
+      # are specified.
+      def check(*validations)
+        raise ArgumentError.new("no validations specified") if validations.empty?
+        lambda {|input| validate(input, validations) }
+      end
+    
+      # Returns a block that loads input strings as YAML, then
+      # calls validate with the result and the input validations.
+      # Non-string inputs are not converted.
+      #
+      #   b = yaml(Integer, nil)
+      #   b.class                 # => Proc
+      #   b.call(1)               # => 1
+      #   b.call("1")             # => 1
+      #   b.call(nil)             # => nil
+      #   b.call("str")           # => ValidationError
+      #
+      # If no validations are specified, the result will be 
+      # returned without validation.
+      def yaml(*validations)
+        lambda do |input|
+          res = input.kind_of?(String) ? yamlize(input) : input
+          validations.empty? ? res : validate(res, validations)
+        end
+      end
+      
+      # Returns a block loads a String input as YAML then
+      # validates the result is valid using the input
+      # validations.  If the input is not a String, the
+      # input is validated directly.
+      def yamlize_and_check(*validations)
+        lambda do |input|
+          input = yamlize(input) if input.kind_of?(String)
+          validate(input, validations)
+        end
+      end
+      
+      # Returns a block that checks the input is a string.
+      # Moreover, strings are re-evaluated as string 
+      # literals using %Q. 
+      #
+      #   string.class              # => Proc
+      #   string.call('str')        # => 'str'
+      #   string.call('\n')         # => "\n"
+      #   string.call("\n")         # => "\n"
+      #   string.call("%s")         # => "%s"
+      #   string.call(nil)          # => ValidationError
+      #   string.call(:sym)         # => ValidationError
+      #
+      def string(); STRING; end
+      string_validation_block = lambda do |input|
+        input = validate(input, [String])
+        eval %Q{"#{input}"}
+      end
+      STRING = string_validation_block
+      
+      # Same as string but allows nil.  Note the special
+      # behavior of the nil string '~' -- rather than
+      # being treated as a string, it is processed as nil
+      # to be consistent with the other [class]_or_nil
+      # methods.
+      #
+      #   string_or_nil.call('~')   # => nil
+      #   string_or_nil.call(nil)   # => nil
+      def string_or_nil(); STRING_OR_NIL; end
+      string_or_nil_validation_block = lambda do |input|
+        input = validate(input, [String, nil])
+        case input
+        when nil, '~' then nil 
+        else eval %Q{"#{input}"}
+        end
+      end
+      STRING_OR_NIL = string_or_nil_validation_block
+      
+      # Returns a block that checks the input is a symbol.
+      # String inputs are loaded as yaml first.
+      #
+      #   symbol.class              # => Proc
+      #   symbol.call(:sym)         # => :sym
+      #   symbol.call(':sym')       # => :sym
+      #   symbol.call(nil)          # => ValidationError
+      #   symbol.call('str')        # => ValidationError
+      #
+      def symbol(); SYMBOL; end
+      SYMBOL = yamlize_and_check(Symbol)
+      
+      # Same as symbol but allows nil:
+      #
+      #   symbol_or_nil.call('~')   # => nil
+      #   symbol_or_nil.call(nil)   # => nil
+      def symbol_or_nil(); SYMBOL_OR_NIL; end
+      SYMBOL_OR_NIL = yamlize_and_check(Symbol, nil)
+      
+      # Returns a block that checks the input is true, false or nil.
+      # String inputs are loaded as yaml first.
+      #
+      #   boolean.class             # => Proc
+      #   boolean.call(true)        # => true
+      #   boolean.call(false)       # => false
+      #   boolean.call(nil)         # => nil
+      #
+      #   boolean.call('true')      # => true
+      #   boolean.call('yes')       # => true
+      #   boolean.call('FALSE')     # => false
+      #
+      #   boolean.call(1)           # => ValidationError
+      #   boolean.call("str")       # => ValidationError
+      #
+      def boolean(); BOOLEAN; end
+      BOOLEAN = yamlize_and_check(true, false, nil)
+      
+      def switch(); SWITCH; end
+      SWITCH = yamlize_and_check(true, false, nil)
+      
+      def flag(); FLAG; end
+      FLAG = yamlize_and_check(true, false, nil)
+
+      # Returns a block that checks the input is an array.
+      # String inputs are loaded as yaml first.
+      #
+      #   array.class               # => Proc
+      #   array.call([1,2,3])       # => [1,2,3]
+      #   array.call('[1, 2, 3]')   # => [1,2,3]
+      #   array.call(nil)           # => ValidationError
+      #   array.call('str')         # => ValidationError
+      #
+      def array(); ARRAY; end
+      ARRAY = yamlize_and_check(Array)
+      
+      # Same as array but allows nil:
+      #
+      #   array_or_nil.call('~')    # => nil
+      #   array_or_nil.call(nil)    # => nil
+      def array_or_nil(); ARRAY_OR_NIL; end
+      ARRAY_OR_NIL = yamlize_and_check(Array, nil)
+      
+      def list(); LIST; end
+      list_block = lambda do |input|
+        if input.kind_of?(String)
+          input = case processed_input = yamlize(input)
+          when Array then processed_input
+          else input.split(/,/).collect {|arg| yamlize(arg) }
+          end
+        end
+        
+        validate(input, [Array])
+      end
+      LIST = list_block
+
+      # Returns a block that checks the input is a hash.
+      # String inputs are loaded as yaml first.
+      #
+      #   hash.class                     # => Proc
+      #   hash.call({'key' => 'value'})  # => {'key' => 'value'}
+      #   hash.call('key: value')        # => {'key' => 'value'}
+      #   hash.call(nil)                 # => ValidationError
+      #   hash.call('str')               # => ValidationError
+      #
+      def hash(); HASH; end
+      HASH = yamlize_and_check(Hash)
+      
+      # Same as hash but allows nil:
+      #
+      #   hash_or_nil.call('~')          # => nil
+      #   hash_or_nil.call(nil)          # => nil
+      def hash_or_nil(); HASH_OR_NIL; end
+      HASH_OR_NIL = yamlize_and_check(Hash, nil)
+      
+      # Returns a block that checks the input is an integer.
+      # String inputs are loaded as yaml first.
+      #
+      #   integer.class             # => Proc
+      #   integer.call(1)           # => 1
+      #   integer.call('1')         # => 1
+      #   integer.call(1.1)         # => ValidationError
+      #   integer.call(nil)         # => ValidationError
+      #   integer.call('str')       # => ValidationError
+      #
+      def integer(); INTEGER; end
+      INTEGER = yamlize_and_check(Integer)
+      
+      # Same as integer but allows nil:
+      #
+      #   integer_or_nil.call('~')  # => nil
+      #   integer_or_nil.call(nil)  # => nil
+      def integer_or_nil(); INTEGER_OR_NIL; end
+      INTEGER_OR_NIL = yamlize_and_check(Integer, nil)
+      
+      # Returns a block that checks the input is a float.
+      # String inputs are loaded as yaml first.
+      #
+      #   float.class               # => Proc
+      #   float.call(1.1)           # => 1.1
+      #   float.call('1.1')         # => 1.1
+      #   float.call('1.0e+6')      # => 1e6
+      #   float.call(1)             # => ValidationError
+      #   float.call(nil)           # => ValidationError
+      #   float.call('str')         # => ValidationError
+      #
+      def float(); FLOAT; end
+      FLOAT = yamlize_and_check(Float)
+      
+      # Same as float but allows nil:
+      #
+      #   float_or_nil.call('~')    # => nil
+      #   float_or_nil.call(nil)    # => nil
+      def float_or_nil(); FLOAT_OR_NIL; end
+      FLOAT_OR_NIL = yamlize_and_check(Float, nil)
+      
+      # Returns a block that checks the input is a number.
+      # String inputs are loaded as yaml first.
+      #
+      #   num.class               # => Proc
+      #   num.call(1.1)           # => 1.1
+      #   num.call(1)             # => 1
+      #   num.call(1e6)           # => 1e6
+      #   num.call('1.1')         # => 1.1
+      #   num.call('1.0e+6')      # => 1e6
+      #   num.call(nil)           # => ValidationError
+      #   num.call('str')         # => ValidationError
+      #
+      def num(); NUMERIC; end
+      NUMERIC = yamlize_and_check(Numeric)
+      
+      # Same as num but allows nil:
+      #
+      #   num_or_nil.call('~')    # => nil
+      #   num_or_nil.call(nil)    # => nil
+      def num_or_nil(); NUMERIC_OR_NIL; end
+      NUMERIC_OR_NIL = yamlize_and_check(Numeric, nil)
+      
+      # Returns a block that checks the input is a regexp.
+      # String inputs are converted to regexps using
+      # Regexp#new.
+      #
+      #   regexp.class              # => Proc
+      #   regexp.call(/regexp/)     # => /regexp/
+      #   regexp.call('regexp')     # => /regexp/
+      #
+      #   # use of ruby-specific flags can turn on/off 
+      #   # features like case insensitive matching
+      #   regexp.call('(?i)regexp') # => /(?i)regexp/
+      #
+      def regexp(); REGEXP; end
+      regexp_block = lambda do |input|
+        input = Regexp.new(input) if input.kind_of?(String)
+        validate(input, [Regexp])
+      end
+      REGEXP = regexp_block
+      
+      # Same as regexp but allows nil. Note the special
+      # behavior of the nil string '~' -- rather than
+      # being converted to a regexp, it is processed as 
+      # nil to be consistent with the other [class]_or_nil
+      # methods.
+      #
+      #   regexp_or_nil.call('~')   # => nil
+      #   regexp_or_nil.call(nil)   # => nil
+      def regexp_or_nil(); REGEXP_OR_NIL; end
+      regexp_or_nil_block = lambda do |input|
+        input = case input
+        when nil, '~' then nil
+        when String then Regexp.new(input)
+        else input
+        end
+        
+        validate(input, [Regexp, nil])
+      end
+      REGEXP_OR_NIL = regexp_or_nil_block
+      
+      # Returns a block that checks the input is a range.
+      # String inputs are split into a beginning and
+      # end if possible, where each part is loaded as
+      # yaml before being used to construct a Range.a
+      #
+      #   range.class               # => Proc
+      #   range.call(1..10)         # => 1..10
+      #   range.call('1..10')       # => 1..10
+      #   range.call('a..z')        # => 'a'..'z'
+      #   range.call('-10...10')    # => -10...10
+      #   range.call(nil)           # => ValidationError
+      #   range.call('1.10')        # => ValidationError
+      #   range.call('a....z')      # => ValidationError
+      #
+      def range(); RANGE; end
+      range_block = lambda do |input|
+        if input.kind_of?(String) && input =~ /^([^.]+)(\.{2,3})([^.]+)$/
+          input = Range.new(yamlize($1), yamlize($3), $2.length == 3) 
+        end
+        validate(input, [Range])
+      end
+      RANGE = range_block
+      
+      # Same as range but allows nil:
+      #
+      #   range_or_nil.call('~')    # => nil
+      #   range_or_nil.call(nil)    # => nil
+      def range_or_nil(); RANGE_OR_NIL; end
+      range_or_nil_block = lambda do |input|
+        input = case input
+        when nil, '~' then nil
+        when String
+          if input =~ /^([^.]+)(\.{2,3})([^.]+)$/
+            Range.new(yamlize($1), yamlize($3), $2.length == 3)
+          else
+            input
+          end
+        else input
+        end
+        
+        validate(input, [Range, nil])
+      end
+      RANGE_OR_NIL = range_or_nil_block
+      
+    end
+  end
 end