bahuvrihi-tap 0.10.7 → 0.10.8

data/lib/tap/support/class_configuration.rb

@@ -5,20 +5,29 @@ require 'tap/support/configuration'
 module Tap
   module Support
     
-    # ClassConfiguration tracks and handles the class configurations defined in a 
-    # Configurable class.
+    # ClassConfiguration tracks configurations defined by a Configurable class.
     class ClassConfiguration
       include Enumerable
       
-      # The class receiving new configurations
+      config_templates_dir = File.expand_path File.dirname(__FILE__) + "/../generator/generators/config/templates"
+
+      # The path to the :doc template (see inspect)
+      DOC_TEMPLATE_PATH = File.join(config_templates_dir, 'doc.erb')
+
+      # The path to the :nodoc template (see inspect)
+      NODOC_TEMPLATE_PATH = File.join(config_templates_dir, 'nodoc.erb')
+      
+      # The Configurable class receiving new configurations
       attr_reader :receiver
 
-      # Tracks the assignment of the config keys to receivers
+      # An Assignments tracking the assignment of config keys to receivers
       attr_reader :assignments
       
-      # A map of (key, config) pairs.
+      # A map of [key, Configuration] pairs
       attr_reader :map
-
+      
+      # Generates a new ClassConfiguration for the receiver.  If a parent is 
+      # provided, configurations will be inherited from it.
       def initialize(receiver, parent=nil)
         @receiver = receiver
         
@@ -34,9 +43,9 @@ module Tap
         end
       end
 
-      # Initializes a Configuration using the inputs and sets it in self
-      # using name as a key, overriding the current config by that name,
-      # if it exists.  Returns the new config.
+      # Initializes a Configuration using the inputs and sets using name 
+      # as a key.  Any existing config by the same name is overridden. 
+      # Returns the new config.
       def add(name, default=nil, attributes={})
         self[name] = Configuration.new(name.to_sym, default, attributes)
       end
@@ -46,12 +55,12 @@ module Tap
         self[key] = nil
       end
       
-      # Gets the configuration specified by key.  The key is symbolized.
+      # Gets the config specified by key.  The key is symbolized.
       def [](key)
         map[key.to_sym]  
       end
       
-      # Assigns the configuration to key.  A nil config unassigns the
+      # Assigns the config to key.  A nil config unassigns the
       # configuration key.  The key is symbolized.
       def []=(key, config)
         key = key.to_sym
@@ -91,7 +100,7 @@ module Tap
       end
       
       # Calls block once for each [receiver, key, config] in self, 
-      # passing those elements as parameters, in the order in
+      # passing those elements as parameters in the order in
       # which they were assigned.  
       def each
         assignments.each do |receiver, key|
@@ -100,7 +109,7 @@ module Tap
       end
       
       # Calls block once for each [key, config] pair in self, 
-      # passing those elements as parameters, in the order in
+      # passing those elements as parameters in the order in
       # which they were assigned.
       def each_pair
         assignments.each do |receiver, key|
@@ -114,7 +123,7 @@ module Tap
         InstanceConfiguration.new(self, receiver, store)
       end
       
-      # Returns a hash of the (key, config.default) values in self.
+      # Returns a hash of the [key, config.default] pairs in self.
       def to_hash
         hash = {}
         each_pair {|key, config| hash[key] = config.default }
@@ -130,36 +139,16 @@ module Tap
         code_comments
       end
       
-      # The path to the :doc template (see format_str)
-      DOC_TEMPLATE_PATH = File.expand_path File.dirname(__FILE__) + "/../generator/generators/config/templates/doc.erb"
-      
-      # The path to the :nodoc template (see format_str)
-      NODOC_TEMPLATE_PATH = File.expand_path File.dirname(__FILE__) + "/../generator/generators/config/templates/nodoc.erb"
-
-      # Formats the configurations using the specified template.  Two default
-      # templates are defined, <tt>:doc</tt> and <tt>:nodoc</tt>.  These map 
-      # to the contents of DOC_TEMPLATE_PATH and NODOC_TEMPLATE_PATH and 
-      # correspond to the documented and undocumented config generator templates.
-      #
-      # == Custom Templates
-      #
-      # format_str initializes a Templater which formats each [receiver, configurations] 
-      # pair in turn, and puts the output to the target using <tt><<</tt>.   The 
-      # templater is assigned the following attributes for use in formatting:
-      #
-      # receiver:: The receiver
-      # configurations:: An array of configurations and associated comments
-      # 
-      # In the template these can be accessed as any ERB locals, for example:
-      #
-      #   <%= receiver.to_s %>
-      #   <% configurations.each do |key, config, comment| %>
-      #   ...
-      #   <% end %>
+      # Inspects the configurations using the specified template.  Templates
+      # are used for format each [receiver, configurations] pair in self.
+      # See DEFAULT_TEMPLATE as a model.  The results of each template cycle
+      # are pushed to target.
       #
-      # The input template may be a String or an ERB; either may be used to 
-      # initialize the templater.
-      def format_str(template=:doc, target="")
+      # Two default templates are defined, <tt>:doc</tt> and <tt>:nodoc</tt>.
+      # These map to the contents of DOC_TEMPLATE_PATH and NODOC_TEMPLATE_PATH
+      # and correspond to the documented and undocumented 
+      # Tap::Generator::Generators::ConfigGenerator templates.
+      def inspect(template=:doc, target="")
         Lazydoc.resolve_comments(code_comments)
         
         template = case template

data/lib/tap/support/combinator.rb

@@ -9,14 +9,14 @@ module Tap
     #   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
+    # 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 Combinator bundles all but the first set into a new 
+    # 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]
@@ -35,14 +35,14 @@ module Tap
     class Combinator
       include Enumerable
       
-      # The first set.
+      # The first set
       attr_reader :a
       
-      # The second set.
+      # The second set
       attr_reader :b
 
-      # Creates a new Combinator.  Input sets must be an Array, or nil.
-      # Within the Array any objects are allowed for combination.
+      # 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)
@@ -71,7 +71,7 @@ module Tap
       end
 
       # Passes each combination as an array to the input block.
-      def each
+      def each # :yields: combination
         case
         when !(@a.empty? || @b.empty?)
           @a.each do |a|

data/lib/tap/support/configurable.rb

@@ -21,7 +21,7 @@ module Tap
     #   c.config.class         # => InstanceConfiguration
     #   c.config               # => {:one => 'one', :two => 'two', :three => 'three'}
     #
-    # The <tt>config</tt> object acts as a kind of forwarding hash; declared configurations
+    # 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'
@@ -33,8 +33,8 @@ module Tap
     #   c.config[:undeclared] = 'value'
     #   c.config.store         # => {:undeclared => 'value'}
     #
-    # The writer method for a configuration can be modified by providing a block to config.  
-    # The Validation module provides a number of common validation and string-transform 
+    # 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
@@ -55,21 +55,21 @@ module Tap
     #   s.two = nil            # !> ValidationError
     #   s.two = 'str'          # !> ValidationError
     #
-    # As shown above, configurations are inherited from the parent and can be
+    # 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)
+      def self.included(mod) # :nodoc:
         mod.extend Support::ConfigurableClass if mod.kind_of?(Class)
       end
       
-      # The instance configurations for self
+      # An InstanceConfiguration with configurations for self
       attr_reader :config
       
-      # Reconfigures self with the given configuration overrides.  Only
-      # the specified configs are modified.  Override keys are symbolized.
+      # Reconfigures self with the given overrides.  Only the specified configs
+      # are modified.  Keys are symbolized.
       #
       # Returns self.
       def reconfigure(overrides={})
@@ -81,9 +81,9 @@ module Tap
         self
       end
       
-      # Reinitializes config with a copy of orig.config (this assures
-      # that duplicates have their own copy of configurations, 
-      # separate from the original object).
+      # 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)
@@ -91,9 +91,8 @@ module Tap
       
       protected
       
-      # Initializes config to an InstanceConfiguration specific for self.
-      # Default config values are assigned or overridden if specified in
-      # overrides. Override keys are symbolized.
+      # 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

data/lib/tap/support/configurable_class.rb

@@ -7,9 +7,9 @@ module Tap
   module Support
     autoload(:Templater, 'tap/support/templater')
     
-    # ConfigurableClass encapsulates class methods used to declare class configurations. 
-    # When configurations are declared using the config method, ConfigurableClass 
-    # generates accessors in the class, much like attr_accessor.  
+    # 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
@@ -22,31 +22,6 @@ module Tap
     #   c.respond_to?('one')                       # => true
     #   c.respond_to?('one=')                      # => true
     # 
-    # If a block is given, the block will be used to create the writer method
-    # for the config.  Used in this manner, config defines a <tt>config_key=</tt> method 
-    # wherein <tt>@config_key</tt> will be set to the return value of the block.
-    #
-    #   class AnotherConfigurableClass
-    #     extend ConfigurableClass
-    #     config(:one, 'one') {|value| value.upcase }
-    #   end
-    #
-    #   ac = AnotherConfigurableClass.new
-    #   ac.one = 'value'
-    #   ac.one               # => 'VALUE'
-    #
-    # The block has class-context in this case.  To have instance-context, use the
-    # config_attr method which defines the writer method using the block directly.
-    #
-    #   class YetAnotherConfigurableClass
-    #     extend ConfigurableClass
-    #     config_attr(:one, 'one') {|value| @one = value.reverse }
-    #   end
-    #
-    #   ac = YetAnotherConfigurableClass.new
-    #   ac.one = 'value'
-    #   ac.one               # => 'eulav'
-    #
     module ConfigurableClass
       include Tap::Support::LazyAttributes
       
@@ -54,7 +29,7 @@ module Tap
       attr_reader :configurations
 
       # Sets the source_file for base and initializes base.configurations.
-      def self.extended(base)
+      def self.extended(base) # :nodoc:
         caller.each_with_index do |line, index|
           case line
           when /\/configurable.rb/ then next
@@ -70,7 +45,7 @@ module Tap
       # 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)
+      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)) 
@@ -80,6 +55,7 @@ module Tap
         super
       end
       
+      # Returns the lazydoc for self.
       def lazydoc(resolve=true)
         Lazydoc.resolve_comments(configurations.code_comments) if resolve
         super

data/lib/tap/support/configuration.rb

@@ -1,8 +1,12 @@
 module Tap
   module Support
+    
+    # Represents a configuration declared by a Configurable class.
     class Configuration
       class << self
-        SHORT_REGEXP = /^-[A-z]$/
+        
+        # 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.
@@ -13,11 +17,12 @@ module Tap
         def shortify(str)
           str = str.to_s
           str = "-#{str}" unless str[0] == ?-
-          raise "invalid short option: #{str}" unless str =~ SHORT_REGEXP
+          raise "invalid short option: #{str}" unless str =~ SHORT_OPTION
           str
         end
-
-        LONG_REGEXP = /^--(\[no-\])?([A-z][\w-]*)$/
+        
+        # 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.
@@ -33,7 +38,7 @@ module Tap
           str = "--#{str}" unless str.index("--")
           str.gsub!(/_/, '-') if hyphenize
           
-          raise "invalid long option: #{str}" unless str =~ LONG_REGEXP
+          raise "invalid long option: #{str}" unless str =~ LONG_OPTION
           
           if switch_notation && $1.nil?
             str = "--[no-]#{$2}"
@@ -43,12 +48,24 @@ module Tap
         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
@@ -59,11 +76,12 @@ module Tap
       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)).
+      # 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 then false
+        when nil, true, false, Symbol, Numeric, Method then false
         else value.respond_to?(:dup)
         end
         
@@ -88,22 +106,29 @@ module Tap
         @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
@@ -119,6 +144,8 @@ module Tap
         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 

data/lib/tap/support/constant.rb

@@ -1,18 +1,79 @@
-require 'tap/support/constant_utils'
-class String # :nodoc:
-  include Tap::Support::ConstantUtils
-end
+require 'tap/support/string_ext'
 
 module Tap
   module Support
+    
+    # A Constant serves as a placeholder for an actual constant, sort of like 
+    # autoload.  Use the constantize method to retrieve the actual constant; 
+    # if it doesn't exist, constantize requires require_path and tries again.
+    #
+    #   Object.const_defined?(:Net)                      # => false
+    #   $".include?('net/http')                          # => false
+    #
+    #   http = Constant.new('Net::HTTP', 'net/http')
+    #   http.constantize                                 # => Net::HTTP
+    #   $".include?('net/http')                          # => true
+    #
     class Constant
+      class << self
+        
+        # Tries to find a declared constant under base with the specified
+        # const_name.  When a constant is missing, constantize yields
+        # the current base and any non-existant constant names the block,
+        # if given, or raises a NameError.  The block is expected 
+        # to return the proper constant.
+        #
+        #   module ConstName; end
+        #
+        #   Constant.constantize('ConstName')                     # => ConstName
+        #   Constant.constantize('Non::Existant') { ConstName }   # => ConstName
+        #
+        def constantize(const_name, base=Object) # :yields: base, missing_const_names
+          unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ const_name
+            raise NameError, "#{const_name.inspect} is not a valid constant name!"
+          end
+          
+          constants = $1.split(/::/)
+          while !constants.empty?
+            unless const_is_defined?(base, constants[0])
+              if block_given? 
+                return yield(base, constants)
+              else
+                raise NameError.new("uninitialized constant #{const_name}", constants[0]) 
+              end
+            end
+            base = base.const_get(constants.shift)
+          end
+          base
+        end
+        
+        private
+        
+        # helper method.  Determines if a constant named
+        # name is defined in const.  The implementation
+        # (annoyingly) has to be different for ruby 1.9
+        # due to changes in the API.
+        case RUBY_VERSION
+        when /^1.9/
+          def const_is_defined?(const, name) # :nodoc:
+            const.const_defined?(name, false)
+          end
+        else
+          def const_is_defined?(const, name) # :nodoc:
+            const.const_defined?(name)
+          end
+        end
+      end
       
-      # The camelized name for self.
+      # The constant name
       attr_reader :name
       
-      # The path to load to initialize the constant name.
+      # The path to load to initialize a missing constant
       attr_reader :require_path
-  
+      
+      # Initializes a new Constant with the specified constant
+      # name and require_path.  The name should be a valid
+      # constant name.
       def initialize(name, require_path=nil)
         @name = name
         @require_path = require_path
@@ -48,9 +109,9 @@ module Tap
         @nesting_depth ||= nesting.split(/::/).length
       end
   
-      # Returns the document for require_path, if set, or nil otherwise.
+      # Returns the Lazydoc document for require_path.
       def document
-        require_path ? Support::Lazydoc[require_path] : nil 
+        require_path ? Lazydoc[require_path] : nil 
       end
       
       # True if another is a Constant with the same name
@@ -63,12 +124,13 @@ module Tap
       
       # Looks up and returns the constant indicated by name.
       # If the constant cannot be found, the constantize
-      # requires require_path and tries again.  Raises an
-      # NameError if the constant cannot be found.
+      # requires require_path and tries again.  
+      #
+      # Raises a NameError if the constant cannot be found.
       def constantize
-        name.try_constantize do |const_name|
+        Constant.constantize(name) do
           require require_path if require_path
-          name.constantize
+          Constant.constantize(name)
         end
       end