tap 0.11.1 → 0.12.0

data/lib/tap/support/combinator.rb

@@ -1,125 +0,0 @@
-require 'enumerator'
-
-module Tap 
-  module Support
-    
-    # Combinator provides a method for iterating over all combinations
-    # of items in the input sets.
-    #
-    #   c = Combinator.new [1,2], [3,4]
-    #   c.to_a            # => [[1,3], [1,4], [2,3], [2,4]]
-    #
-    # Combinators can take any object that responds to each as an
-    # input set; normally arrays are used.
-    #
-    # === Implementation
-    #
-    # Combinator iteratively combines each element from the first set (a)
-    # with each element from the second set (b).  When more than two sets
-    # are given, the second and remaining sets are bundled into a
-    # Combinator, which then acts as the second set.
-    #
-    #   c = Combinator.new [1,2], [3,4], [5,6]
-    #   c.a               # => [[1],[2]]
-    #   c.b.class         # => Combinator
-    #   c.b.a             # => [[3],[4]]
-    #   c.b.b             # => [[5],[6]]
-    #
-    # Note that internally each item in a set is stored as a single-item
-    # array; the arrays are added during combination.  Thus when 
-    # iterating, the combinations are calculated like:
-    #
-    #   ([1] + [3]) + [5] # => [1,3,5]
-    #
-    # This is probably not the fastest implementation, but it works.
-    class Combinator
-      include Enumerable
-      
-      # The first set
-      attr_reader :a
-      
-      # The second set
-      attr_reader :b
-
-      # Creates a new Combinator.  Each input must respond
-      # to each, or be nil.
-      def initialize(*sets)
-        @a = make_set(sets.shift)
-        @b = make_set(*sets)
-      end
-
-      # Returns the sets used to initialize the Combinator.
-      def sets
-        sets_in(a) + sets_in(b)
-      end
-
-      # True if length is zero.
-      def empty?
-        a.empty? && b.empty?
-      end
-
-      # Returns the number of combinations returned by each.
-      def length
-        case
-        when !(@a.empty? || @b.empty?)
-          @a.length * @b.length
-        when @a.empty? 
-          @b.length
-        when @b.empty?
-          @a.length
-        end
-      end
-
-      # Passes each combination as an array to the input block.
-      def each # :yields: combination
-        case
-        when !(@a.empty? || @b.empty?)
-          @a.each do |a|
-            @b.each do |b|
-              yield(a + b)
-            end
-          end
-        when @a.empty? 
-          @b.each {|b| yield(b) }
-        when @b.empty? 
-          @a.each {|a| yield(a) }
-        end
-      end
-
-      private
-      
-      # makes a Combinator out of multiple sets or collects the
-      # objects of a single set as arrays:
-      #
-      #   make_set([1,2,3], [4,5,6])  # => Combinator.new([1,2,3], [4,5,6])
-      #   make_set([1,2,3])           # => [[1],[2],[3]]
-      #
-      def make_set(*sets) # :nodoc:
-        # recieves an array of arrays or combinators
-        return Combinator.new(*sets) if sets.length > 1 
-        return sets if sets.empty?
-        
-        set = sets[0]
-        return [] if set == nil
-        
-        unless set.respond_to?(:each)
-          raise ArgumentError, "does not respond to each: #{set}"
-        end
-        
-        # recursively arrayifies each element
-        arrayified_set = []
-        set.each {|s| arrayified_set << [s]}
-        arrayified_set
-      end
-
-      # basically the reverse of make_set
-      def sets_in(set) # :nodoc:
-        case set
-        when Combinator then set.sets
-        when Array then set.empty? ? [] : [set.collect {|s| s[0]}]
-        end
-      end
-      
-    end
-  end
-end

data/lib/tap/support/configurable.rb

@@ -1,113 +0,0 @@
-require 'tap/support/configurable_class'
-
-module Tap
-  module Support
-    
-    # Configurable enables the specification of configurations within a class definition.
-    #
-    #   class ConfigClass
-    #     include Configurable
-    # 
-    #     config :one, 'one'
-    #     config :two, 'two'
-    #     config :three, 'three'
-    #
-    #     def initialize(overrides={})
-    #       initialize_config(overrides)
-    #     end
-    #   end
-    #
-    #   c = ConfigClass.new
-    #   c.config.class         # => InstanceConfiguration
-    #   c.config               # => {:one => 'one', :two => 'two', :three => 'three'}
-    #
-    # The <tt>config</tt> object acts as a forwarding hash; declared configurations
-    # map to accessors while undeclared configurations are stored internally:
-    #
-    #   c.config[:one] = 'ONE'
-    #   c.one                  # => 'ONE'
-    #
-    #   c.one = 1           
-    #   c.config               # => {:one => 1, :two => 'two', :three => 'three'}
-    #
-    #   c.config[:undeclared] = 'value'
-    #   c.config.store         # => {:undeclared => 'value'}
-    #
-    # The writer for a configuration can be defined by providing a block to config.  
-    # The Validation module provides a number of common validation/transform 
-    # blocks which can be accessed through the class method 'c':
-    #
-    #   class SubClass < ConfigClass
-    #     config(:one, 'one') {|v| v.upcase }
-    #     config :two, 2, &c.integer
-    #   end
-    #
-    #   s = SubClass.new
-    #   s.config               # => {:one => 'ONE', :two => 2, :three => 'three'}
-    #
-    #   s.one = 'aNothER'             
-    #   s.one                  # => 'ANOTHER'
-    #
-    #   s.two = -2
-    #   s.two                  # => -2
-    #   s.two = "3"
-    #   s.two                  # => 3
-    #   s.two = nil            # !> ValidationError
-    #   s.two = 'str'          # !> ValidationError
-    #
-    # As shown above, configurations are inherited from the parent and may be
-    # overridden in subclasses.  See ConfigurableClass for more details.
-    #
-    module Configurable
-      
-      # Extends including classes with ConfigurableClass
-      def self.included(mod) # :nodoc:
-        mod.extend Support::ConfigurableClass if mod.kind_of?(Class)
-      end
-      
-      # An InstanceConfiguration with configurations for self
-      attr_reader :config
-      
-      # Reconfigures self with the given overrides.  Only the specified configs
-      # are modified.  Keys are symbolized.
-      #
-      # Returns self.
-      def reconfigure(overrides={})
-        keys = (config.class_config.ordered_keys + overrides.keys) & overrides.keys
-        keys.each do |key|
-          config[key.to_sym] = overrides[key] 
-        end
-
-        self
-      end
-      
-      # Reinitializes configurations in the copy such that
-      # the new object has it's own set of configurations,
-      # separate from the original object.
-      def initialize_copy(orig)
-        super
-        initialize_config(orig.config)
-      end
-      
-      protected
-      
-      # Initializes config to an InstanceConfiguration. Default config values 
-      # are overridden as specified by overrides. Keys are symbolized.
-      def initialize_config(overrides={})
-        class_config = self.class.configurations
-        @config = class_config.instance_config
-        
-        overrides.each_pair do |key, value|
-          config[key.to_sym] = value
-        end
-        
-        class_config.each_pair do |key, value|
-          next if config.has_key?(key)
-          config[key] = value.default
-        end
-
-        config.bind(self)
-      end
-    end
-  end
-end

data/lib/tap/support/configurable_class.rb

@@ -1,271 +0,0 @@
-require 'tap/support/class_configuration'
-require 'tap/support/validation'
-require 'tap/support/lazy_attributes'
-require 'tap/support/lazydoc/config'
-
-module Tap
-  module Support
-    autoload(:Templater, 'tap/support/templater')
-    
-    # ConfigurableClass defines class methods used by a Configurable class to
-    # declare configurations.  In addition to registering key-value pairs,
-    # these methods generate readers and writers, much like attr_accessor.  
-    #
-    #   class ConfigurableClass
-    #     extend ConfigurableClass
-    #     config :one, 'one'
-    #   end
-    #
-    #   ConfigurableClass.configurations.to_hash   # => {:one => 'one'}
-    #
-    #   c = ConfigurableClass.new
-    #   c.respond_to?('one')                       # => true
-    #   c.respond_to?('one=')                      # => true
-    # 
-    module ConfigurableClass
-      include Tap::Support::LazyAttributes
-      
-      # A ClassConfiguration holding the class configurations.
-      attr_reader :configurations
-
-      # Sets the source_file for base and initializes base.configurations.
-      def self.extended(base) # :nodoc:
-        caller.each_with_index do |line, index|
-          case line
-          when /\/configurable.rb/ then next
-          when Lazydoc::CALLER_REGEXP
-            base.instance_variable_set(:@source_file, File.expand_path($1))
-            break
-          end
-        end
-        
-        base.instance_variable_set(:@configurations, ClassConfiguration.new(base))
-      end
-
-      # When subclassed, the parent.configurations are duplicated and passed to 
-      # the child class where they can be extended/modified without affecting
-      # the configurations of the parent class.
-      def inherited(child) # :nodoc:
-        unless child.instance_variable_defined?(:@source_file)
-          caller.first =~ Lazydoc::CALLER_REGEXP
-          child.instance_variable_set(:@source_file, File.expand_path($1)) 
-        end
-        
-        child.instance_variable_set(:@configurations, ClassConfiguration.new(child, @configurations))
-        super
-      end
-      
-      # Returns the lazydoc for self.
-      def lazydoc(resolve=true)
-        Lazydoc.resolve_comments(configurations.code_comments) if resolve
-        super
-      end
-      
-      # Loads the contents of path as YAML.  Returns an empty hash if the path 
-      # is empty, does not exist, or is not a file.
-      def load_config(path)
-        # the last check prevents YAML from auto-loading itself for empty files
-        return {} if path == nil || !File.file?(path) || File.size(path) == 0
-        YAML.load_file(path) || {}
-      end
-      
-      protected
-      
-      # Declares a class configuration and generates the associated accessors. 
-      # If a block is given, the <tt>key=</tt> method will set <tt>@key</tt> 
-      # to the return of the block, which executes in class-context.  
-      # Configurations are inherited, and can be overridden in subclasses. 
-      #
-      #   class SampleClass
-      #     include Tap::Support::Configurable
-      #
-      #     config :str, 'value'
-      #     config(:upcase, 'value') {|input| input.upcase } 
-      #   end
-      #
-      #   # An equivalent class to illustrate class-context
-      #   class EquivalentClass
-      #     attr_accessor :str
-      #     attr_reader :upcase
-      #
-      #     UPCASE_BLOCK = lambda {|input| input.upcase }
-      #
-      #     def upcase=(input)
-      #       @upcase = UPCASE_BLOCK.call(input)
-      #     end
-      #   end
-      #
-      def config(key, value=nil, options={}, &block)
-        if block_given?
-          # add arg_type implied by block, if necessary
-          options[:arg_type] = arg_type(block) if options[:arg_type] == nil
-          options[:arg_name] = arg_name(block) if options[:arg_name] == nil
-          
-          instance_variable = "@#{key}".to_sym
-          config_attr(key, value, options) do |input|
-            instance_variable_set(instance_variable, block.call(input))
-          end
-        else
-          config_attr(key, value, options)
-        end
-      end
-      
-      # Declares a class configuration and generates the associated accessors. 
-      # If a block is given, the <tt>key=</tt> method will perform the block with
-      # instance-context.  Configurations are inherited, and can be overridden 
-      # in subclasses. 
-      #
-      #   class SampleClass
-      #     include Tap::Support::Configurable
-      #
-      #     def initialize
-      #       initialize_config
-      #     end
-      #
-      #     config_attr :str, 'value'
-      #     config_attr(:upcase, 'value') {|input| @upcase = input.upcase } 
-      #   end
-      #
-      #   # An equivalent class to illustrate instance-context
-      #   class EquivalentClass
-      #     attr_accessor :str
-      #     attr_reader :upcase
-      #
-      #     def upcase=(input)
-      #       @upcase = input.upcase
-      #     end
-      #   end
-      #
-      # Instances of a Configurable class may set configurations through config.
-      # The config object is an InstanceConfiguration which forwards read/write 
-      # operations to the configuration accessors.  For example:
-      #
-      #   s = SampleClass.new
-      #   s.config.class            # => Tap::Support::InstanceConfiguration
-      #   s.str                     # => 'value'
-      #   s.config[:str]            # => 'value'
-      #
-      #   s.str = 'one'
-      #   s.config[:str]            # => 'one'
-      #   
-      #   s.config[:str] = 'two' 
-      #   s.str                     # => 'two'
-      # 
-      # Alternative reader and writer methods may be specified as an option;
-      # in this case config_attr assumes the methods are declared elsewhere
-      # and will not define the associated accessors.  
-      # 
-      #   class AlternativeClass
-      #     include Tap::Support::Configurable
-      #
-      #     config_attr :sym, 'value', :reader => :get_sym, :writer => :set_sym
-      #
-      #     def initialize
-      #       initialize_config
-      #     end
-      #
-      #     def get_sym
-      #       @sym
-      #     end
-      #
-      #     def set_sym(input)
-      #       @sym = input.to_sym
-      #     end
-      #   end
-      #
-      #   alt = AlternativeClass.new
-      #   alt.respond_to?(:sym)     # => false
-      #   alt.respond_to?(:sym=)    # => false
-      #   
-      #   alt.config[:sym] = 'one'
-      #   alt.get_sym               # => :one
-      #
-      #   alt.set_sym('two')
-      #   alt.config[:sym]          # => :two
-      #
-      # Idiosyncratically, true, false, and nil may also be provided as 
-      # reader/writer options. Specifying true is the same as using the 
-      # default.  Specifying false or nil prevents config_attr from 
-      # defining accessors; false sets the configuration to use 
-      # the default reader/writer methods (ie <tt>key</tt> and <tt>key=</tt>,
-      # which must be defined elsewhere) while nil prevents read/write
-      # mapping of the config to a method.
-      def config_attr(key, value=nil, options={}, &block)
-        
-        # add arg_type implied by block, if necessary
-        options[:arg_type] = arg_type(block) if block_given? && options[:arg_type] == nil
-        options[:arg_name] = arg_name(block) if block_given? && options[:arg_name] == nil
-
-        # define the default public reader method
-        if !options.has_key?(:reader) || options[:reader] == true
-          attr_reader(key) 
-          public key
-        end
-        
-        # define the public writer method
-        case
-        when options.has_key?(:writer) && options[:writer] != true
-          raise(ArgumentError, "a block may not be specified with writer option") if block_given?
-        when block_given? 
-          define_method("#{key}=", &block)
-          public "#{key}="
-        else
-          attr_writer(key)
-          public "#{key}="
-        end
-
-        # remove any true, false reader/writer declarations...
-        # implicitly reverting the option to the default reader
-        # and writer methods
-        [:reader, :writer].each do |option|
-          case options[option]
-          when true, false then options.delete(option)
-          end
-        end
-        
-        # register with Lazydoc so that all extra documentation can be extracted
-        caller.each do |line|
-          case line
-          when /in .config.$/ then next
-          when Lazydoc::CALLER_REGEXP
-            options[:desc] = Lazydoc.register($1, $3.to_i - 1, Lazydoc::Config)
-            break
-          end
-        end if options[:desc] == nil
-        
-        configurations.add(key, value, options)
-      end
-
-      # Alias for Tap::Support::Validation
-      def c
-        Validation
-      end
-      
-      private
-      
-      # Returns special argument types for standard validation
-      # blocks, such as switch (Validation::SWITCH) and list
-      # (Validation::LIST).
-      def arg_type(block) # :nodoc:
-        case 
-        when block == Validation::SWITCH then :switch
-        when block == Validation::FLAG then :flag
-        when block == Validation::LIST then :list
-        else nil
-        end
-      end
-      
-      # Returns special argument names for standard validation
-      # blocks, such as switch (Validation::ARRAY) and list
-      # (Validation::HASH).
-      def arg_name(block) # :nodoc:
-        case
-        when block == Validation::ARRAY then "'[a, b, c]'"
-        when block == Validation::HASH then "'{one: 1, two: 2}'"
-        else nil
-        end
-      end
-
-    end
-  end
-end