bahuvrihi-tap 0.11.2 → 0.12.0

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/lazydoc/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 Lazydoc::Attributes
-      
-      # 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

data/lib/tap/support/configuration.rb

@@ -1,170 +0,0 @@
-module Tap
-  module Support
-    
-    # Represents a configuration declared by a Configurable class.
-    class Configuration
-      class << self
-        
-        # Matches a short option
-        SHORT_OPTION = /^-[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_OPTION
-          str
-        end
-        
-        # Matches a long option
-        LONG_OPTION = /^--(\[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_OPTION
-          
-          if switch_notation && $1.nil?
-            str = "--[no-]#{$2}"
-          end
-
-          str
-        end
-      end
-      
-      # The name of the configuration
-      attr_reader :name
-      
-      # The reader method, by default name
-      attr_reader :reader
-      
-      # The writer method, by default name=
-      attr_reader :writer
-      
-      # True if the default value may be duplicated
-      attr_reader :duplicable
-      
-      # An array of optional metadata for self
-      attr_reader :attributes
-      
-      # Initializes a new Configuration with the specified name and default
-      # value.  Options may specify an alternate reader/writer; any
-      # additional options are set as attributes.
-      def initialize(name, default=nil, options={})
-        @name = name
-        self.default = default
-        
-        self.reader = options.has_key?(:reader) ? options.delete(:reader) : name
-        self.writer = options.has_key?(:writer) ? options.delete(:writer) : "#{name}="
-        @attributes = options
-      end
-
-      # Sets the default value for self and determines if the
-      # default is duplicable.  Non-duplicable values include
-      # nil, true, false, Symbol, Numeric, and any object that
-      # does not respond to dup.
-      def default=(value)
-        @duplicable = case value
-        when nil, true, false, Symbol, Numeric, Method 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,
-      # but may also be set to nil.
-      def reader=(value)
-        @reader = value == nil ? value : value.to_sym
-      end
-      
-      # Sets the writer for self.  The writer is symbolized,
-      # but may also be set to nil.
-      def writer=(value)
-        @writer = value == nil ? value : value.to_sym
-      end
-      
-      # The argument name for self: either attributes[:arg_name]
-      # or name.to_s.upcase
-      def arg_name
-        attributes[:arg_name] || name.to_s.upcase
-      end
-      
-      # The argument type for self: either attributes[:arg_type]
-       # or :mandatory
-      def arg_type
-        attributes[:arg_type] || :mandatory
-      end
-      
-      # The long version of name.
-      def long(switch_notation=false, hyphenize=true)
-        Configuration.longify(attributes[:long] || name.to_s, switch_notation, hyphenize)
-      end
-      
-      # The short version of name.
-      def short
-        attributes[:short] ? Configuration.shortify(attributes[:short]) : nil
-      end
-      
-      # The description for self: attributes[:desc]
-      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
-      
-      # Returns self as an argv that can be used to register
-      # an option with OptionParser.
-      def to_optparse_argv
-        argtype = case arg_type
-        when :optional 
-          "#{long} [#{arg_name}]"
-        when :switch 
-          long(true)
-        when :flag
-          long
-        when :list
-          "#{long} a,b,c"
-        when :mandatory, nil
-          "#{long} #{arg_name}"
-        else
-          raise "unknown arg_type: #{arg_type}"
-        end
-
-        [short, argtype, desc].compact
-      end
-      
-    end
-  end
-end