configurable 0.1.0 → 0.3.0

data/lib/config_parser/option.rb

@@ -1,35 +1,63 @@
 require 'config_parser/utils'
 
-class ConfigParser  
+class ConfigParser
+  
+  # Represents an option registered with ConfigParser.
   class Option
-
+    
+    # A format string used by to_s
+    LINE_FORMAT = "%-36s %-43s"
+    
+    # The short switch mapping to self
     attr_reader :short 
+    
+    # The long switch mapping to self
     attr_reader :long
+    
+    # The argument name printed by to_s.  If arg_name
+    # is nil, no value will be parsed for self.
     attr_reader :arg_name
-    attr_reader :desc     
+    
+    # The description printed by to_s
+    attr_reader :desc
+    
+    # The block called when one of the switches mapping
+    # to self is parse; block will receive the parsed
+    # argument if arg_name is specified.
     attr_reader :block
     
-    def initialize(options={}, &block)
-      @short = Utils.shortify(options[:short])
-      @long = Utils.longify(options[:long])
-      @arg_name = options[:arg_name]
-      @desc = options[:desc]
+    # Initializes a new Option using attribute values for :long, :short,
+    # :arg_name, and :desc.  The long and short values are transformed 
+    # using Utils.longify and Utils.shortify, meaning both bare strings
+    # (ex 'opt', 'o') and full switches ('--opt', '-o') are valid.
+    def initialize(attributes={}, &block)
+      @short = Utils.shortify(attributes[:short])
+      @long = Utils.longify(attributes[:long])
+      @arg_name = attributes[:arg_name]
+      @desc = attributes[:desc]
       @block = block
     end
     
-    # Returns an array of non-nil switches mapping to this option 
-    # (ie [long, short]).  May be overridden in subclasses.
+    # Returns an array of non-nil switches mapping to self (ie [long, short]).
     def switches
       [long, short].compact
     end
-
-    # Selects the value or the shifts a value off of argv and sets
-    # that value in config.  
+    
+    # Parse determines how an option is actually parsed from an argv.  Parse 
+    # recieves the switch mapping to self for cases in which it affects the 
+    # outcome (see Switch).  By default parse has two modes of action:
+    #
+    # ==== Argument-style option (arg_name is specified)
+    #
+    # If arg_name is set, then parse passes value to the block. If no value
+    # is specified, the next argument in argv is used instead.  An error
+    # is raised if no value can be found.
+    #
+    # ==== Flag-style option (no arg_name is specified)
+    # 
+    # In this case, parse simply calls the block.  If a non-nil value is
+    # specified, parse raises an error.
     #
-    # Parse is a hook for fancier ways of determining an option
-    # value and/or setting the value in config.  Parse recieves 
-    # the switch (ie long or short) mapping to self for subclasses
-    # that need it (ex the Switch class).
     def parse(switch, value, argv)
       if arg_name
         unless value
@@ -42,11 +70,32 @@ class ConfigParser
         block ? block.call : nil
       end
     end
-
+    
+    # Formats self as a help string for use on the command line.
     def to_s
-      short_str = short ? short + ',' : '   '
-      desc_str = desc.kind_of?(Lazydoc::Comment) ? desc.trailer : desc
-      "%-37s%-43s" % ["    #{short_str} #{long} #{arg_name}", desc_str]
+      lines = Lazydoc::Utils.wrap(desc.to_s, 43)
+      
+      header =  "    #{short_str} #{long_str} #{arg_name}"
+      header = header.length > 36 ? header.ljust(80) : (LINE_FORMAT % [header, lines.shift])
+      
+      if lines.empty?
+        header
+      else
+        lines.collect! {|line| LINE_FORMAT % [nil, line] }
+        "#{header}\n#{lines.join("\n")}"
+      end
+    end
+    
+    private
+    
+    # helper returning short formatted for to_s
+    def short_str # :nodoc:
+      short ? short + ',' : '   '
+    end
+    
+    # helper returning long formatted for to_s
+    def long_str # :nodoc:
+      long
     end
   end
 end

data/lib/config_parser/switch.rb

@@ -1,29 +1,44 @@
-class ConfigParser 
+class ConfigParser
+  
+  # Switch represents a special type of Option where both a positive
+  # (--switch) and negative (--no-switch) version of long should
+  # map to self.  A short may be specified for Switch; it will always
+  # be treated like the positive switch.
   class Switch < Option
+    
+    # The negative long switch, determined from long.
     attr_reader :negative_long
-
+    
+    # Initializes a new Switch.  Raises an error if an arg_name is
+    # specified for self (as switches are intended to be boolean
+    # in nature), or if no long option is specified.
     def initialize(options={})
       super
       raise ArgumentError, "arg_name specified for switch: #{arg_name}" if arg_name
       raise ArgumentError, "no long specified" unless long
-      @negative_long = Utils.longify("no-#{long[2,long.length-2]}")
+      @negative_long = Utils.prefix_long(long, 'no-')
     end
-
+    
+    # Returns an array of non-nil switches mapping to self (ie 
+    # [long, negative_long, short]).
     def switches
       [long, negative_long, short].compact
     end
-
+    
+    # Calls the block with false if the negative long is specified,
+    # or calls the block with true in all other cases.  Raises an
+    # error if a value is specified.
     def parse(switch, value, argv)
       raise "value specified for switch" if value
       value = (switch == negative_long ? false : true)
       block ? block.call(value) : value
     end
 
-    def to_s
-      short_str = short ? short + ',' : '   '
-      long_str = long ? "--[no-]#{long[2,long.length-2]}" : ''
-      desc_str = desc.kind_of?(Lazydoc::Comment) ? desc.trailer : desc
-      "%-37s%-43s" % ["    #{short_str} #{long_str}", desc_str]
+    private
+    
+    # helper returning long formatted for to_s
+    def long_str # :nodoc:
+      long ? Utils.prefix_long(long, '[no-]') : ''
     end
   end
 end

data/lib/config_parser/utils.rb

@@ -1,4 +1,6 @@
 class ConfigParser
+  
+  # A medly of methods used throughout the ConfigParser classes.
   module Utils
     module_function
     
@@ -34,8 +36,8 @@ class ConfigParser
     # an error if the option does not match SHORT_OPTION.  Nils
     # are returned directly.
     #
-    #   ConfigParser.shortify("-o")         # => '-o'
-    #   ConfigParser.shortify(:o)           # => '-o'
+    #   shortify("-o")         # => '-o'
+    #   shortify(:o)           # => '-o'
     #
     def shortify(str)
       return nil if str == nil
@@ -52,9 +54,9 @@ class ConfigParser
     # are converted to hyphens. Raises an error if the option does
     # not match LONG_OPTION.  Nils are returned directly.
     #
-    #   ConfigParser.longify("--opt")       # => '--opt'
-    #   ConfigParser.longify(:opt)          # => '--opt'
-    #   ConfigParser.longify(:opt_ion)      # => '--opt-ion'
+    #   longify("--opt")       # => '--opt'
+    #   longify(:opt)          # => '--opt'
+    #   longify(:opt_ion)      # => '--opt-ion'
     #
     def longify(str)
       return nil if str == nil
@@ -68,58 +70,70 @@ class ConfigParser
       str
     end
     
-    # Options:
+    # Adds a prefix onto the last nested segment of a long option.
+    #
+    #   prefix_long("--opt", 'no-')         # => '--no-opt'
+    #   prefix_long("--nested:opt", 'no-')  # => '--nested:no-opt'
+    #
+    def prefix_long(switch, prefix, split_char=':')
+      switch = switch[2,switch.length-2] if switch =~ /^--/
+      switch = switch.split(split_char)
+      switch[-1] = "#{prefix}#{switch[-1]}"
+      "--#{switch.join(':')}"
+    end
+    
+    # Attributes:
     #
     #   :long      the long key ("--key") 
     #   :arg_name  the argument name ("KEY") 
     #
-    def setup_option(key, options={})
-      options[:long] ||= "--#{key}"
-      options[:long].to_s =~ /^(--)?(.*)$/ 
-      options[:arg_name] ||= $2.upcase
+    def setup_option(key, attributes={})
+      attributes[:long] ||= "--#{key}"
+      attributes[:long].to_s =~ /^(--)?(.*)$/ 
+      attributes[:arg_name] ||= $2.upcase
       
       lambda {|value| config[key] = value }
     end
     
-    # Options:
+    # Attributes:
     #
     #   :long      the long key ("--key") 
     #
-    def setup_flag(key, default=true, options={})
-      options[:long] ||= "--#{key}"
+    def setup_flag(key, default=true, attributes={})
+      attributes[:long] ||= "--#{key}"
       
       lambda {config[key] = !default }
     end
     
-    # Options:
+    # Attributes:
     #
     #   :long      the long key ("--[no-]key") 
     #
-    def setup_switch(key, default=true, options={})
-      options[:long] ||= "--#{key}"
-      options[:long].to_s =~ /^(--)?(\[no-\])?(.*)$/ 
-      options[:long] = "--[no-]#{$3}" unless $2
+    def setup_switch(key, default=true, attributes={})
+      attributes[:long] ||= "--#{key}"
+      attributes[:long].to_s =~ /^(--)?(\[no-\])?(.*)$/ 
+      attributes[:long] = "--[no-]#{$3}" unless $2
       
-      lambda {|value| config[key] = (value ? !default : default) }
+      lambda {|value| config[key] = value }
     end
     
-    # Options:
+    # Attributes:
     #
     #   :long      the long key ("--key")
     #   :arg_name  the argument name ("KEY" or "A,B,C" for a comma split) 
     #   :split     the split character
     #
-    def setup_list(key, options={})
-      options[:long] ||= "--#{key}"
+    def setup_list(key, attributes={})
+      attributes[:long] ||= "--#{key}"
       
-      if split = options[:split]
-        options[:arg_name] ||= %w{A B C}.join(split)
+      if split = attributes[:split]
+        attributes[:arg_name] ||= %w{A B C}.join(split)
       else
-        options[:long].to_s =~ /^(--)?(.*)$/ 
-        options[:arg_name] ||= $2.upcase
+        attributes[:long].to_s =~ /^(--)?(.*)$/ 
+        attributes[:arg_name] ||= $2.upcase
       end
       
-      n = options[:n]
+      n = attributes[:n]
       
       lambda do |value|
         array = (config[key] ||= [])

data/lib/configurable.rb

@@ -1,6 +1,7 @@
 require 'configurable/class_methods'
 
-# Configurable enables the specification of configurations within a class definition.
+# Configurable enables the specification of configurations within a class 
+# definition.
 #
 #   class ConfigClass
 #     include Configurable
@@ -9,17 +10,15 @@ require 'configurable/class_methods'
 #     config :two, 'two'
 #     config :three, 'three'
 #
-#     def initialize(overrides={})
-#       initialize_config(overrides)
-#     end
 #   end
 #
 #   c = ConfigClass.new
 #   c.config.class         # => Configurable::DelegateHash
 #   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:
+# Instances have a <tt>config</tt> object that acts like a forwarding hash; 
+# configuration keys delegate to accessors while undeclared key-value pairs
+# are stored internally:
 #
 #   c.config[:one] = 'ONE'
 #   c.one                  # => 'ONE'
@@ -32,7 +31,7 @@ require 'configurable/class_methods'
 #
 # 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':
+# blocks accessible through the class method 'c':
 #
 #   class SubClass < ConfigClass
 #     config(:one, 'one') {|v| v.upcase }
@@ -52,12 +51,39 @@ require 'configurable/class_methods'
 #   s.two = nil            # !> ValidationError
 #   s.two = 'str'          # !> ValidationError
 # 
-# Configurations are inherited from the parent and may be overridden in
-# subclasses.
+# Note that config blocks are defined in class-context and will have access
+# to variables outside the block (as you would expect).  For instance, these
+# are analagous declarations:
+#
+#   class ClassConfig
+#     config :key, 'value' do |input|
+#       input.upcase
+#     end
+#   end
+#
+#   class AnalagousClass
+#     block = lambda {|input| input.upcase}
+#
+#     define_method(:key=) do |input|
+#       @key = block.call(input)
+#     end
+#   end
+#
+# To have the block literally define the writer, use the config_attr method.
+# Blocks provided to config_attr will have instance context and must set 
+# the instance variable themselves.
+#
+#   class ConfigClass
+#     config_attr :key, 'value' do |input|
+#       @key = input.upcase
+#     end
+#   end
+#
+# Configurations are inherited and may be overridden in subclasses.
 #
-# === Options
+# === Attributes
 #
-# Alternative reader and writer methods may be specified as options to config.
+# Alternative reader and writer methods may be specified as config attributes.
 # When alternate methods are specified, Configurable assumes the methods are 
 # declared elsewhere and will not define accessors.  
 # 
@@ -66,10 +92,6 @@ require 'configurable/class_methods'
 #
 #     config_attr :sym, 'value', :reader => :get_sym, :writer => :set_sym
 #
-#     def initialize
-#       initialize_config
-#     end
-#
 #     def get_sym
 #       @sym
 #     end
@@ -89,8 +111,8 @@ require 'configurable/class_methods'
 #   alt.set_sym('two')
 #   alt.config[:sym]          # => :two
 #
-# Idiosyncratically, true, false, and nil may also be provided as 
-# reader/writer options. 
+# Idiosyncratically, true, false, and nil may also be provided as reader/writer
+# options. 
 #
 #   true     Same as using the defaults, accessors are defined.
 #
@@ -102,25 +124,39 @@ require 'configurable/class_methods'
 #            that does not map to the instance, but will be
 #            present in instance.config
 #
+# ==== Non-reader/writer attributes
+#
+# Metadata for a config may be specified in attributes as well.  Attributes like
+# :desc, and :type are used by ConfigParser, for instance, to determine how to
+# represent the configuration on the command line.  Attributes are unstructured
+# so they can accomodate metadata for multiple contexts (ex a web or desktop 
+# interface), as needed.
+#
 module Configurable
-
+  autoload(:Utils, 'configurable/utils')
+  
   # Extends including classes with Configurable::ClassMethods
   def self.included(mod) # :nodoc:
     mod.extend ClassMethods if mod.kind_of?(Class)
   end
 
-  # A ConfigHash bound to self
+  # A DelegateHash bound to self
   attr_reader :config
+  
+  # Initializes config, if necessary, and then calls super.  If initialize
+  # is overridden without calling super, be sure to call initialize_config
+  # manually within the new initialize method.
+  def initialize(*args)
+    initialize_config unless instance_variable_defined?(:@config)
+    super
+  end
 
-  # Reconfigures self with the given overrides. Only the specified configs
-  # are modified. Keys are symbolized.
+  # Reconfigures self with the given overrides. Only the 
+  # specified configs are modified.
   #
   # Returns self.
   def reconfigure(overrides={})
-    overrides.each_pair do |key, value|
-      config[key] = value
-    end
-
+    config.merge!(overrides)
     self
   end
 
@@ -129,7 +165,7 @@ module Configurable
   # separate from the original object.
   def initialize_copy(orig)
     super
-    initialize_config(orig.config)
+    initialize_config(orig.config.dup)
   end
 
   protected
@@ -137,19 +173,7 @@ module Configurable
   # Initializes config. Default config values 
   # are overridden as specified by overrides.
   def initialize_config(overrides={})
-    delegates = self.class.configurations
-
-    # note the defaults could be stored first and overridden
-    # by the overrides, but this is likely more efficient
-    # on average since delegates duplicate default values.
-    store = {}
-    overrides.each_pair do |key, value| 
-      store[key] = value
-    end
-    delegates.each_pair do |key, delegate|
-      store[key] = delegate.default unless store.has_key?(key)
-    end
-
-    @config = DelegateHash.new(delegates, store).bind(self)
+    @config = overrides.kind_of?(DelegateHash) ? overrides : DelegateHash.new(self.class.configurations, overrides)
+    @config.bind(self)
   end
 end