config_parser 0.1.0 → 0.2.0

data/History

@@ -1,3 +1,7 @@
+== 0.2.0 / 2010-08-01
+
+Release candidate with cleaner implementation and accurate documentation.
+
 == 0.1.0 / 2010-07-25
 
 Initial release after extraction and cleanup from Configurable. Intended as a

data/README

@@ -7,14 +7,14 @@ Parse command-line options into a configuration hash.
 ConfigParser is an analogue of
 {OptionParser}[http://www.ruby-doc.org/core/classes/OptionParser.html] that
 formalizes the pattern of setting parsed options into a hash. ConfigParser
-uses a similar, simplified declaration syntax that places less emphasis on the
-conversion of inputs to objects, preferring instead to delegate that
-responsibility to whatever consumes the hash.
+uses a similar, simplified declaration syntax and provides an API that
+integrates well with libraries like
+{Configurable}[http://tap.rubyforge.org/configurable].
 
 == Usage
 
-ConfigParser can be used much like OptionParser, where the parser itself can
-be used as a delegate to a config hash.
+ConfigParser can be used much like OptionParser, where the parser can set
+values into a config hash.
 
   parser = ConfigParser.new
   parser.on '-s', '--long LONG', 'a standard option' do |value|
@@ -46,31 +46,42 @@ ConfigParser formalizes this pattern of setting values into a config hash as
 they occur, and adds the ability to specify default values.
 
   parser = ConfigParser.new
-  parser.add(:key, 'default')
+  parser.add :flag, false            # false as a default makes a --flag
+  parser.add :switch, true           # true makes a --[no-]switch
+  parser.add :list, []               # an array makes a list-style option
+  parser.add :opt, 'default'         # all others make an ordinary option
 
-  parser.parse('a b --key option c')             # => ['a', 'b', 'c']
-  parser.config                                  # => {:key => 'option'}
-                                                 
-  parser.parse('a b c')                          # => ['a', 'b', 'c']
-  parser.config                                  # => {:key => 'default'}
+  parser.parse('a b c')              # => ['a', 'b', 'c']
+  parser.config
+  # => {
+  #   :flag   => false,
+  #   :switch => true,
+  #   :list   => [],
+  #   :opt    => 'default'
+  # }
+  
+  args = %w{a b --flag --no-switch --list one --list two,three --opt value c}
+  parser.parse(args)                 # => ['a', 'b', 'c']
+  parser.config
+  # => {
+  #   :flag   => true,
+  #   :switch => false,
+  #   :list   => ['one', 'two', 'three'],
+  #   :opt    => 'value'
+  # }
 
-Config keys may be mapped to options using arguments like those given to 'on',
-or using an options hash. A block can be given to processes values before they
-are set as configs.
+Options can be defined using arguments just like on, or with an attributes
+hash. A block can be given to process values before they are set as configs.
 
   parser = ConfigParser.new
-  parser.add(:x, nil, '-o', '--one', 'by args') {|value| value.upcase }
+  parser.add(:x, nil, '--one', 'by args') {|value| value.upcase }
   parser.add(:y, nil, :long => 'two', :desc => 'by hash')
   
-  parser.parse('a b --one value --two c')
+  parser.parse('a b --one value --two value c')
   # => ['a', 'b', 'c']
   
   parser.config
-  # => {:x => 'VALUE', :y => true}
-
-ConfigParser integrates well with libraries like
-{Configurable}[http://tap.rubyforge.org/configurable] that are designed to set
-configurations via a config hash.
+  # => {:x => 'VALUE', :y => 'value'}
 
 == Installation
 

data/lib/config_parser.rb

@@ -1,114 +1,11 @@
 require 'config_parser/list'
 autoload(:Shellwords, 'shellwords')
 
-# ConfigParser is the Configurable equivalent of 
-# {OptionParser}[http://www.ruby-doc.org/core/classes/OptionParser.html]
-# and uses a similar, simplified (see below) syntax to declare options.
-#
-#   opts = {}
-#   parser = ConfigParser.new do |psr|
-#     psr.on "-s", "--long LONG", "a standard option" do |value|
-#       opts[:long] = value
-#     end
-#   
-#     psr.on "--[no-]switch", "a switch" do |value|
-#       opts[:switch] = value
-#     end
-#
-#     psr.on "--flag", "a flag" do
-#       # note: no value is parsed; the block 
-#       # only executes if the flag is found
-#       opts[:flag] = true
-#     end
-#   end
-#
-#   parser.parse("a b --long arg --switch --flag c")   # => ['a', 'b', 'c']
-#   opts             # => {:long => 'arg', :switch => true, :flag => true}
-#
-# ConfigParser formalizes this pattern of setting values in a hash as they
-# occur, and adds the ability to specify default values.  The syntax is
-# not quite as friendly as for ordinary options, but meshes well with
-# Configurable classes:
-#
-#   psr = ConfigParser.new
-#   psr.define(:key, 'default', :desc => 'a standard option')
-#
-#   psr.parse('a b --key option c')                 # => ['a', 'b', 'c']
-#   psr.config                                      # => {:key => 'option'}
-#
-#   psr.parse('a b c')                              # => ['a', 'b', 'c']
-#   psr.config                                      # => {:key => 'default'}
-#
-# And now directly from a Configurable class, the equivalent of the
-# original example:
-#
-#   class ConfigClass
-#     include Configurable
-#
-#     config :long, 'default', :short => 's'  # a standard option
-#     config :switch, false, &c.switch        # a switch
-#     config :flag, false, &c.flag            # a flag
-#   end
-#
-#   psr = ConfigParser.new
-#   psr.add(ConfigClass.configurations)
-#
-#   psr.parse("a b --long arg --switch --flag c")   # => ['a', 'b', 'c']
-#   psr.config    # => {:long => 'arg', :switch => true, :flag => true}
-#
-#   psr.parse("a b --long=arg --no-switch c")       # => ['a', 'b', 'c']
-#   psr.config    # => {:long => 'arg', :switch => false, :flag => false}
-#
-#   psr.parse("a b -sarg c")                        # => ['a', 'b', 'c']
-#   psr.config    # => {:long => 'arg', :switch => false, :flag => false}
-#
-# As you might expect, config attributes are used by ConfigParser to 
-# correctly build a corresponding option.  In configurations like :switch, 
-# the block implies the {:type => :switch} attribute and so the
-# config is made into a switch-style option by ConfigParser.
-#
-# Use the to_s method to convert a ConfigParser into command line
-# documentation:
-#
-#   "\nconfigurations:\n#{psr.to_s}"
-#   # => %q{
-#   # configurations:
-#   #     -s, --long LONG                  a standard option
-#   #         --[no-]switch                a switch
-#   #         --flag                       a flag
-#   # }
-#
-# ==== Simplifications
-#
-# ConfigParser simplifies the OptionParser syntax for 'on'.  ConfigParser does
-# not support automatic conversion of values, gets rid of 'optional' arguments
-# for options, and only supports a single description string.  Hence:
-#
-#   psr = ConfigParser.new
-#  
-#   # incorrect, raises error as this will look
-#   # like multiple descriptions are specified
-#   psr.on("--delay N", 
-#          Float,
-#          "Delay N seconds before executing")        # !> ArgumentError
-#
-#   # correct
-#   psr.on("--delay N", "Delay N seconds before executing") do |value|
-#     value.to_f
-#   end
-#
-#   # this ALWAYS requires the argument and raises
-#   # an error because multiple descriptions are
-#   # specified
-#   psr.on("-i", "--inplace [EXTENSION]",
-#          "Edit ARGV files in place",
-#          "  (make backup if EXTENSION supplied)")   # !> ArgumentError
-#
-#   # correct
-#   psr.on("-i", "--inplace EXTENSION", 
-#          "Edit ARGV files in place\n  (make backup if EXTENSION supplied)")
-#
-#
+# ConfigParser is an option parser that formalizes the pattern of setting
+# parsed options into a hash. ConfigParser provides a similar declaration
+# syntax as
+# {OptionParser}[http://www.ruby-doc.org/core/classes/OptionParser.html] but
+# additionally supports option declaration using an attributes hash.
 class ConfigParser
   include Utils
   
@@ -120,20 +17,24 @@ class ConfigParser
   # '--long' to the Option that handles them.
   attr_reader :options
   
-  # The hash receiving configurations produced by parse.
+  # The hash receiving configs.
   attr_accessor :config
   
   # The argument to stop processing options
   attr_accessor :option_break
   
-  # Set to true to preserve the break argument
+  # Set to true to preserve the option break
   attr_accessor :preserve_option_break
   
+  # Set to true to assign config defaults on parse
+  attr_accessor :assign_defaults
+  
   # Initializes a new ConfigParser and passes it to the block, if given.
   def initialize(config={}, opts={})
     opts = {
       :option_break => OPTION_BREAK,
-      :preserve_option_break => false
+      :preserve_option_break => false,
+      :assign_defaults => true
     }.merge(opts)
     
     @registry = []
@@ -141,6 +42,7 @@ class ConfigParser
     @config = config
     @option_break = opts[:option_break]
     @preserve_option_break = opts[:preserve_option_break]
+    @assign_defaults = opts[:assign_defaults]
     
     yield(self) if block_given?
   end
@@ -160,8 +62,9 @@ class ConfigParser
     @registry << str
   end
 
-  # Registers the option with self by adding opt to options and mapping the
-  # opt flags. Raises an error for conflicting flags.
+  # Registers the option with self by adding it to the registry and mapping
+  # the option flags into options. Raises an error for conflicting flags.
+  # Returns self.
   #
   # If override is specified, options with conflicting flags are removed and
   # no error is raised.  Note that this may remove multiple options.
@@ -187,102 +90,86 @@ class ConfigParser
       @options[flag] = option
     end
     
-    option
+    self
+  end
+  
+  # Unregisters the option by removing it from the registry and options.
+  # Returns self.
+  def unregister(option)
+    @registry.delete(option)
+    @options.delete_if {|key, value| option == value }
+    self
   end
   
-  # Constructs an Option using args and registers it with self.  Args may
+  # Constructs an Option using args and registers it with self. The args may
   # contain (in any order) a short switch, a long switch, and a description
-  # string.  Either the short or long switch may signal that the option
-  # should take an argument by providing an argument name.
+  # string. A block may be provided to process values for the option.
+  #
+  # The option type (flag, switch, list, or option) is guessed from the args,
+  # and affects what is passed to the block.
   #
   #   psr = ConfigParser.new
   #
-  #   # this option takes an argument
-  #   psr.on('-s', '--long ARG_NAME', 'description') do |value|
+  #   # options take an argument on the long
+  #   # and receive the arg in the block
+  #   psr.on('-s', '--long ARG_NAME', 'description') do |arg|
   #     # ...
   #   end
   #
-  #   # so does this one
-  #   psr.on('-o ARG_NAME', 'description') do |value|
+  #   # the argname can be specified on a short
+  #   psr.on('-o ARG_NAME') do |arg|
   #     # ...
   #   end
-  #   
-  #   # this option does not
-  #   psr.on('-f', '--flag') do
+  #       
+  #   # use an argname with commas to make a list,
+  #   # an array of values is passed to the block
+  #   psr.on('--list A,B,C') do |args|
   #     # ...
   #   end
   #
-  # A switch-style option can be specified by prefixing the long switch with
-  # '--[no-]'.  Switch options will pass true to the block for the positive
-  # form and false for the negative form.
+  #   # flags specify no argument, and the
+  #   # block takes no argument
+  #   psr.on('-f', '--flag') do
+  #     # ...
+  #   end
   #
-  #   psr.on('--[no-]switch') do |value|
+  #   # switches look like this; they get true
+  #   # or false in the block
+  #   psr.on('--[no-]switch') do |bool|
   #     # ...
   #   end
   #
-  # Args may also contain a trailing hash defining all or part of the option:
+  # If this is too ambiguous (and at times it is), provide a trailing hash
+  # defining all or part of the option:
   #
-  #   psr.on('-k', :long => '--key', :desc => 'description')
+  #   psr.on('-k', 'description', :long => '--key', :type => :list) do |args|
   #     # ...
   #   end
-  #
+  #   
+  # The trailing hash wins if there is any overlap in the parsed attributes
+  # and those provided by the hash.
   def on(*args, &block)
-    register new_option(args, &block)
+    option = new_option(args, &block)
+    register option
+    option
   end
   
-  # Same as on, but overrides options with overlapping switches.
+  # Same as on, but overrides options with overlapping flags.
   def on!(*args, &block)
-    register new_option(args, &block), true
+    option = new_option(args, &block)
+    register option, true
+    option
   end
   
-  # Defines and registers a config-style option with self.  Define does not
-  # take a block; the default value will be added to config, and any parsed
-  # value will override the default.  Normally the key will be turned into
-  # the long switch; specify an alternate long, a short, description, etc
-  # using attributes.
+  # An alternate syntax for on, where the key and default attributes are set
+  # by the first two args.  Like on, add can define option attributes using a
+  # series of args or with a trailing hash.
   #
-  #   psr = ConfigParser.new
-  #   psr.define(:one, 'default')
-  #   psr.define(:two, 'default', :long => '--long', :short => '-s')
-  #
-  #   psr.parse("--one one --long two")
-  #   psr.config             # => {:one => 'one', :two => 'two'}
+  # These are equivalent:
   #
-  # Define support several types of configurations that define a special 
-  # block to handle the values parsed from the command line.  See the 
-  # 'setup_<type>' methods in Utils.  Any type with a corresponding setup
-  # method is valid:
-  #   
-  #   psr = ConfigParser.new
-  #   psr.define(:flag, false, :type => :flag)
-  #   psr.define(:switch, false, :type => :switch)
-  #   psr.define(:list, [], :type => :list)
-  #
-  #   psr.parse("--flag --switch --list one --list two --list three")
-  #   psr.config             # => {:flag => true, :switch => true, :list => ['one', 'two', 'three']}
-  #
-  # New, valid types may be added by implementing new setup_<type> methods
-  # following this pattern:
-  #
-  #   module SpecialType
-  #     def setup_special(key, default_value, attributes)
-  #       # modify attributes if necessary
-  #       attributes[:long] = "--#{key}"
-  #       attributes[:arg_name] = 'ARG_NAME'
-  # 
-  #       # return a block handling the input
-  #       lambda {|input| config[key] = input.reverse }
-  #     end
-  #   end
+  #   add(:opt, 'value', '-s', '--long', :desc => 'description')
+  #   on('-s', '--long', :desc => 'description', :key => :opt, :default => 'value')
   #
-  #   psr = ConfigParser.new.extend SpecialType
-  #   psr.define(:opt, false, :type => :special)
-  #
-  #   psr.parse("--opt value")
-  #   psr.config             # => {:opt => 'eulav'}
-  #
-  # The :hidden type causes no configuration to be defined.  Raises an error if
-  # key is already set by a different option.
   def add(key, default=nil, *args, &block)
     attrs = args.last.kind_of?(Hash) ? args.pop : {}
     attrs = attrs.merge(:key => key, :default => default)
@@ -291,17 +178,25 @@ class ConfigParser
     on(*args, &block)
   end
   
-  # Parses options from argv in a non-destructive manner and returns an
-  # array of arguments remaining after options have been removed. If a 
-  # string argv is provided, it will be splits into an array using 
-  # Shellwords.
-  #
-  # ==== Options
-  #
-  # clear_config:: clears the currently parsed configs (true)
-  # add_defaults:: adds the default values to config (true)
-  # ignore_unknown_options:: causes unknown options to be ignored (false)
+  # Removes options by key.  Any options with the specified key are removed.
+  # Returns self.
+  def rm(key)
+    options.values.each do |option| 
+      if option.key == key 
+        unregister(option)
+      end
+    end
+    
+    self
+  end
+  
+  # Parses options from argv in a non-destructive manner. Parsing stops if an
+  # argument matching option_break is reached. If preserve_option_break is
+  # specified then the option break is preserved in the remaining arguments. 
+  # Returns an array of arguments remaining after options have been removed.
   #
+  # If a string argv is provided, it will be splits into an array using
+  # Shellwords.
   def parse(argv=ARGV)
     argv = argv.dup unless argv.kind_of?(String)
     parse!(argv)
@@ -311,21 +206,20 @@ class ConfigParser
   def parse!(argv=ARGV)
     argv = Shellwords.shellwords(argv) if argv.kind_of?(String)
     
-    args = []
-    remainder = scan(argv) {|arg| args << arg }
-    args.concat(remainder)
-    argv.replace(args)
+    if assign_defaults
+      registry.each do |option|
+        next unless option.respond_to?(:assign)
+        option.assign(config)
+      end
+    end
     
-    argv
-  end
-  
-  def scan(argv=ARGV)
+    args = []
     while !argv.empty?
       arg = argv.shift
   
       # determine if the arg is an option
-      unless arg.kind_of?(String) && arg[0] == ?-
-        yield(arg)
+      unless option?(arg)
+        args << arg
         next
       end
       
@@ -357,11 +251,14 @@ class ConfigParser
       option.parse(flag, value, argv, config)
     end
     
+    args.concat(argv)
+    argv.replace(args)
+    
     argv
   end
   
-  # Converts the options and separators in self into a help string suitable for
-  # display on the command line.
+  # Converts the options and separators in self into a help string suitable
+  # for display on the command line.
   def to_s
     @registry.collect do |option|
       option.to_s.rstrip
@@ -387,7 +284,7 @@ class ConfigParser
   # by on and on! to generate options
   def new_option(argv, &block) # :nodoc:
     attrs = argv.last.kind_of?(Hash) ? argv.pop : {}
-    attrs = attrs.merge parse_attrs(argv)
+    attrs = parse_attrs(argv).merge(attrs)
     option_class(attrs).new(attrs, &block)
   end
 end

data/lib/config_parser/flag.rb

@@ -1,12 +1,19 @@
 require 'config_parser/utils'
 
 class ConfigParser
+  
+  # Represents a boolean flag-style option. Flag handles the parsing of
+  # specific flags, and provides hooks for processing the various types of
+  # options (Switch, Option, List).
   class Flag
     include Utils
     
     # The config key
     attr_reader :key
     
+    # The config nesting keys
+    attr_reader :nest_keys
+    
     # The default value
     attr_reader :default
     
@@ -23,25 +30,30 @@ class ConfigParser
     attr_reader :callback
     
     def initialize(attrs={}, &callback)
-      @key   = attrs[:key]
-      @default = attrs[:default]
-      @short = shortify(attrs[:short])
-      @long  = longify(attrs.has_key?(:long) ? attrs[:long] : key)
-      @desc  = attrs[:desc]
-      @callback = callback
+      @key       = attrs[:key]
+      @nest_keys = attrs[:nest_keys]
+      @default   = attrs[:default]
+      @short     = shortify(attrs[:short])
+      @long      = longify(attrs.has_key?(:long) ? attrs[:long] : key)
+      @desc      = attrs[:desc]
+      @callback  = callback
     end
     
-    # Returns an array of non-nil flags mapping to self (ie [long, short]).
+    # Returns an array of flags mapping to self (ie [long, short]).
     def flags
       [long, short].compact
     end
     
-    # Assigns true into config and raises an error if a value is provided
-    # (flags take none).  The callback will be called if specified to provide
-    # the assigned value.
+    # Parse handles the parsing of flags, which happens in three steps:
+    #
+    # * determine the value (occurs in parse)
+    # * process the value
+    # * assign the result into config
     #
-    # Note this is the entry point for handling different types of
-    # configuration flags.
+    # Flag uses !default as the value (such that the flag indicates true if
+    # the default is false) then passes the value to process, and then assign.
+    # Raises and error if provided a value directly (flags always determine
+    # their value based on the default).
     #
     #--
     # Implementation Note
@@ -56,7 +68,7 @@ class ConfigParser
     #   -xvalue -y
     #   -y -xvalue
     #   -yxvalue
-    #      
+    #         
     # Whereas this is not:
     #
     #   -xyvalue                   # x receives 'yvalue' not 'value'
@@ -65,22 +77,42 @@ class ConfigParser
     # 'xvalue'. Then '-y' determines whether or not it needs a values; if not
     # '-xvalue' gets unshifted to argv and parsing continues as if '-y
     # -xvalue' were the original arguments.
-    def parse(flag, value, argv=[], config={})
+    def parse(flag, value=nil, argv=[], config={})
       unless value.nil?
         if flag == short
           argv.unshift "-#{value}"
         else
-          raise "value specified for flag: #{flag}"
+          raise "value specified for #{flag}: #{value.inspect}"
         end
       end
       
-      assign(config, callback ? callback.call : default.nil? ? false : default)
+      value = (default.nil? ? true : !default)
+      assign(config, process(value))
     end
     
-    # Assign the value to the config hash, if key is set.  Returns value.
-    def assign(config, value)
-      config[key] = value if key
-      value
+    # Process the value by calling the callback, if specified, with the value
+    # and returns the result.  Returns value if no callback is specified.
+    def process(value)
+      callback ? callback.call(value) : value
+    end
+    
+    # Assign the value to the config hash, if key is set.  Returns config.
+    def assign(config, value=default)
+      if key
+        nest_config = nest(config)
+        nest_config[key] = value
+      end
+      
+      config
+    end
+    
+    # Returns the nested config hash for config, as specified by nest_keys.
+    def nest(config)
+      nest_keys.each do |key|
+        config = (config[key] ||= {})
+      end if nest_keys
+      
+      config
     end
     
     # Formats self as a help string for use on the command line.
@@ -104,7 +136,6 @@ class ConfigParser
       "    #{short_str}#{long_str}"
     end
     
-    # helper returning short formatted for to_s
     def short_str # :nodoc:
       case
       when short && long then "#{short}, "
@@ -113,7 +144,6 @@ class ConfigParser
       end
     end
     
-    # helper returning long formatted for to_s
     def long_str # :nodoc:
       long
     end

data/lib/config_parser/list.rb

@@ -1,38 +1,61 @@
 require 'config_parser/option'
 
 class ConfigParser
+  
+  # List represents a special type of Option where multiple values may be
+  # assigned to the same key.
   class List < Option
     
     # The default split character for multiple values
-    DEFAULT_SPLIT = ','
+    DELIMITER = ','
     
-    # The maximum number of values that may be specified.
+    # The maximum number of values that may be specified; nil for unlimited.
     attr_reader :limit
     
-    # The sequence on which to split single values into multiple values. Set
-    # to nil to prevent split.
-    attr_reader :split
+    # The delimiter on which to split single values into multiple values; use
+    # nil to prevent splitting.
+    attr_reader :delimiter
     
     def initialize(attrs={})
       super
-      @limit = attrs[:n]
-      @split = attrs.has_key?(:split) ? attrs[:split] : DEFAULT_SPLIT
+      
+      @delimiter = attrs.has_key?(:delimiter) ? attrs[:delimiter] : DELIMITER
+      @limit   = attrs[:limit]
+      @default = split(@default)
+    end
+    
+    # Splits the value into multiple values, and then process as usual.
+    def process(value)
+      super split(value)
     end
     
-    # List assigns configs by pushing the value onto an array, rather than
-    # directly setting it onto config.  As usual, no value is assigned if key
-    # is not set.  Returns value (the input, not the array).
-    def assign(config, value)
+    # Assigns the values to config by concatenating onto an array, rather than
+    # directly setting into config.  As usual, no value is assigned if key is
+    # not set.
+    def assign(config, values=default)
       if key
-        array = (config[key] ||= [])
-        array.concat(split ? value.split(split) : [value])
+        nest_config = nest(config)
+        array = (nest_config[key] ||= [])
+        array.concat(values)
       
         if limit && array.length > limit
-          raise "too many assignments: #{key.inspect}"
+          raise "too many assignments for #{key.inspect}"
         end
       end
       
-      value
+      config
+    end
+    
+    # Splits string values along the delimiter, if specified.  Returns array
+    # values directly, and an empty array for nil.  All other values are
+    # arrayified like [obj].
+    def split(obj)
+      case obj
+      when Array  then obj
+      when String then delimiter ? obj.split(delimiter) : [obj]
+      when nil    then []
+      else [obj]
+      end
     end
   end
 end

data/lib/config_parser/option.rb

@@ -2,37 +2,46 @@ require 'config_parser/switch'
 
 class ConfigParser
   
-  # Represents an option registered with ConfigParser.
+  # An Option represents a Flag that takes a value.
   class Option < Flag
+    
+    # The default argument name
     DEFAULT_ARGNAME = 'VALUE'
     
+    # Matches optional argnames
+    OPTIONAL = /\A\[.*\]\z/
+    
     # The argument name printed by to_s.
     attr_reader :arg_name
     
+    # Set to true to make the argument optional
+    attr_reader :optional
+    
     def initialize(attrs={})
       super
       @arg_name = attrs[:arg_name] || (key ? key.to_s.upcase : DEFAULT_ARGNAME)
+      @optional = (attrs.has_key?(:optional) ? attrs[:optional] : (arg_name =~ OPTIONAL ? true : false))
     end
     
     # Parse the flag and value.  If no value is provided and a value is
-    # required, then a value is shifted off of argv.  Calls the callback
-    # with the value, if specified, and assigns the result.
-    def parse(flag, value, argv=[], config={})
+    # required, then a value is shifted off of argv.  The value is then
+    # processed and assigned into config.
+    def parse(flag, value=nil, argv=[], config={})
       if value.nil?
         unless value = next_arg(argv)
-          raise "no value provided for: #{flag}"
+          if optional
+            value = default
+          else
+            raise "no value provided for: #{flag}"
+          end
         end
       end
-      assign(config, callback ? callback.call(value) : value)
+      
+      assign(config, process(value))
     end
     
     private
     
-    def next_arg(argv) # :nodoc:
-      arg = argv[0]
-      (arg.kind_of?(String) && arg[0] == ?-) ? default : argv.shift
-    end
-    
     def header_str # :nodoc:
       "    #{short_str}#{long_str} #{arg_name}"
     end

data/lib/config_parser/switch.rb

@@ -6,38 +6,40 @@ class ConfigParser
   # and negative (--no-flag) flags map to self.
   class Switch < Flag
     
-    # The negative long flag, determined from long if not set otherwise.
-    attr_reader :negative_long
+    # The negative mapping prefix, defaults to 'no'
+    attr_reader :prefix
+    
+    # The negative long flag, determined from long and prefix.
+    attr_reader :nolong
     
     def initialize(attrs={})
       attrs[:default] = true unless attrs.has_key?(:default)
       super
       
       raise ArgumentError, "no long specified" unless long
-      @negative_long = attrs[:negative_long] || prefix_long(long, 'no-')
+      @prefix = attrs[:prefix] || 'no'
+      @nolong = prefix_long(long, "#{prefix}-")
     end
     
-    # Returns an array of non-nil flags mapping to self (ie [long,
-    # negative_long, short]).
+    # Returns an array of flags mapping to self (ie [long, nolong, short]).
     def flags
-      [long, negative_long, short].compact
+      [long, nolong, short].compact
     end
     
-    # Assigns true into config for positive flags and false for negative
-    # flags.  If specified, the callback is called with the boolean to
-    # determine the assigned value.  Raises an error if a value is provided
-    # (switches take none).
-    def parse(flag, value, argv=[], config={})
-      raise "value specified for switch: #{flag}" if value
-      value = (flag == negative_long ? !default : default)
-      assign(config, callback ? callback.call(value) : value)
+    # Assigns default into config for positive flags and !default for negative
+    # flags. The boolean value is then processed and assigned into config.
+    # Raises an error if a value is provided (switches take none).
+    def parse(flag, value=nil, argv=[], config={})
+      raise "value specified for #{flag}: #{value.inspect}" if value
+      
+      value = (flag == nolong ? !default : default)
+      assign(config, process(value))
     end
 
     private
     
-    # helper returning long formatted for to_s
     def long_str # :nodoc:
-      long ? prefix_long(long, '[no-]') : ''
+      prefix_long(long, "[#{prefix}-]")
     end
   end
 end

data/lib/config_parser/utils.rb

@@ -10,19 +10,30 @@ class ConfigParser
     # The default option break
     OPTION_BREAK = "--"
     
+    # Matches an option (long or short)
+    OPTION = /\A-./
+    
     # Matches a long flag
     LONG_FLAG = /\A--.+\z/
 
     # Matches a short flag
     SHORT_FLAG = /\A-.\z/
     
-    # Matches a switch declaration (ex: '--[no-]opt', '--nest:[no-]opt').
-    # After the match:
-    #  
+    # Matches a switch option (ex: '--[no-]opt', '--nest:[no-]opt'). After the
+    # match:
+    #   
     #   $1:: the nesting prefix ('nest')
-    #   $2:: the long flag name ('opt')
+    #   $2:: the nolong prefix ('no')
+    #   $3:: the long flag name ('opt')
     #
-    SWITCH = /\A--(.*?)\[no-\](.+)\z/
+    SWITCH = /\A--(.*?)\[(.*?)-\](.+)\z/
+    
+    # Matches a nest option (ex: '--nest:opt').  After the match:
+    #
+    #   $1:: the nesting prefix ('nest')
+    #   $2:: the long option ('long')
+    #
+    NEST = /\A--(.*):(.+)\z/
     
     # Turns the input into a short flag by prefixing '-' (as needed). Raises
     # an error if the input doesn't result in a short flag.   Nils are
@@ -35,7 +46,7 @@ class ConfigParser
       return nil if str.nil?
   
       str = str.to_s
-      str = "-#{str}" unless str[0] == ?-
+      str = "-#{str}" unless option?(str)
       
       unless str =~ SHORT_FLAG
         raise ArgumentError, "invalid short flag: #{str}"
@@ -55,7 +66,7 @@ class ConfigParser
       return nil if str.nil?
   
       str = str.to_s
-      str = "--#{str}" unless str[0] == ?-
+      str = "--#{str}" unless option?(str)
       
       unless str =~ LONG_FLAG
         raise ArgumentError, "invalid long flag: #{str}"
@@ -76,6 +87,17 @@ class ConfigParser
       "--#{switch.join(':')}"
     end
     
+    # Returns true if the object is a string and matches OPTION.
+    def option?(obj)
+      obj.kind_of?(String) && obj =~ OPTION ? true : false
+    end
+    
+    # Shifts and returns the first argument off of argv if it is an argument
+    # (rather than an option) or returns the default value.
+    def next_arg(argv)
+      option?(argv.at(0)) ? nil : argv.shift
+    end
+    
     # A wrapping algorithm slightly modified from:
     # http://blog.macromates.com/2006/wrapping-text-with-regular-expressions/
     def wrap(line, cols=80, tabsize=2)
@@ -83,16 +105,39 @@ class ConfigParser
       line.gsub(/(.{1,#{cols}})( +|$\r?\n?)|(.{1,#{cols}})/, "\\1\\3\n").split(/\s*?\n/)
     end
     
+    # Parses the argv into an attributes hash for initializing an option.
+    # Heuristics are used to infer what an argument implies.
+    #  
+    #   Argument            Implies
+    #   -s                  :short => '-s'
+    #   --long              :long => '--long'
+    #   --long ARG          :long => '--long', :arg_name => 'ARG'
+    #   --[no-]long         :long => '--long', :prefix => 'no', :type => :switch
+    #   --nest:long         :long => '--nest:long', :nest_keys => ['nest']
+    #   'some string'       :desc => 'some string'
+    #
+    # Usually you overlay these patterns, for example:
+    #
+    #   -s ARG              :short => '-s', :arg_name => 'ARG'
+    #   --nest:[no-]long    :long => '--nest:long', :nest_keys => ['nest'], :prefix => 'no', :type => :switch
+    #
+    # The goal of this method is to get things right most of the time, not to
+    # be clean, simple, or robust.  Some errors in declarations (like an
+    # arg_name with a switch) can be detected... others not so much.
     def parse_attrs(argv)
       attrs={}
       
       argv.each do |arg|
-        if arg[0] != ?-
+        unless option?(arg)
           attrs[:desc] = arg
           next
         end
 
         flag, arg_name = arg.split(/\s+/, 2)
+        
+        if flag =~ NEST
+          attrs[:nest_keys] = $1.split(':')
+        end
 
         if arg_name
           attrs[:arg_name] = arg_name
@@ -100,9 +145,9 @@ class ConfigParser
 
         case flag
         when SWITCH
-          attrs[:long] = "--#{$1}#{$2}"
-          attrs[:negative_long] = "--#{$1}no-#{$2}"
-
+          attrs[:long] = "--#{$1}#{$3}"
+          attrs[:prefix] = $2
+          
           if arg_name
             raise ArgumentError, "arg_name specified for switch: #{arg_name}"
           end
@@ -121,15 +166,49 @@ class ConfigParser
       attrs
     end
     
-    def guess_type(attrs) # :nodoc:
+    # Guesses an option type based on the attrs.
+    #
+    #   if...            then...
+    #   prefix      =>   :switch
+    #   arg_name    =>   guess_type_by_arg_name || guess_type_by_value
+    #   default     =>   (guess_type_by_value)
+    #   all else    =>   :flag
+    #
+    # A guess is just a guess; for certainty specify the type manually.
+    def guess_type(attrs)
       case
-      when attrs[:negative_long]
+      when attrs.has_key?(:prefix)
         :switch
-      when attrs[:arg_name] || attrs[:default]
-        :option
+      when attrs.has_key?(:arg_name)
+        guess_type_by_arg_name(attrs[:arg_name]) || guess_type_by_value(attrs[:default])
+      when attrs.has_key?(:default)
+        guess_type_by_value(attrs[:default])
       else
         :flag
       end
     end
+    
+    # Guesses :list if the arg_name has a comma, or nil.
+    def guess_type_by_arg_name(arg_name)
+      arg_name.to_s.include?(',') ? :list : nil
+    end
+    
+    # Guesses an option type based on a value.
+    #
+    #   if...            then...
+    #   true        =>   :switch
+    #   false       =>   :flag
+    #   Array       =>   :list
+    #   all else    =>   :option
+    #
+    # A guess is just a guess; for certainty specify the type manually.
+    def guess_type_by_value(value)
+      case value
+      when true  then :switch
+      when false then :flag
+      when Array then :list
+      else :option
+      end
+    end
   end
 end

data/lib/config_parser/version.rb

@@ -1,6 +1,6 @@
 class ConfigParser
   MAJOR = 0
-  MINOR = 1
+  MINOR = 2
   TINY = 0
 
   VERSION="#{MAJOR}.#{MINOR}.#{TINY}"

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Simon Chiang
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-25 00:00:00 -06:00
+date: 2010-08-01 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency