configurable 0.5.0 → 0.6.0

data/History

@@ -1,3 +1,22 @@
+== 0.6.0 / 2009-12-05
+
+* minor bug fixes in interface
+* added on! to ConfigParser to specify override options
+* updates to use latest Lazydoc
+* added scrub to DelegateHash#to_hash, to remove keys
+  set to the default value
+* added strbol validation
+* nil long options are now respected
+* refactored default_config to defaults in ConfigParser
+* refactored Validation register syntax
+* added scan method to ConfigParser
+* ConfigParser can no longer ignore unknown options
+* added configurable option breaks to ConfigParser
+* refactored Delegate to Config, and simplified
+  implementation for nesting to use NestConfig
+* refactored :duplicate_default attribute to :dup
+* added undef_config and remove_config methods
+
 == 0.5.0 / 2009-05-25
 
 * fixed io validation to not duplicate IOs

data/MIT-LICENSE

@@ -1,19 +1,21 @@
 Copyright (c) 2008-2009, Regents of the University of Colorado.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this
-software and associated documentation files (the "Software"), to deal in the Software
-without restriction, including without limitation the rights to use, copy, modify, merge,
-publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
-to whom the Software is furnished to do so, subject to the following conditions:
+Copyright (c) 2009, Simon Chiang.
 
-The above copyright notice and this permission notice shall be included in all copies or
-substantial portions of the Software.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README

@@ -9,45 +9,103 @@ are inheritable, delegate to methods, and have hash-like access. Configurable
 maps configurations to the command line through ConfigParser and is used by
 the Tap[http://tap.rubyforge.org] framework.
 
-Check out these links for development, and bug tracking.
+Check out these links for development and bug tracking.
 
 * Website[http://tap.rubyforge.org/configurable]
 * Github[http://github.com/bahuvrihi/configurable/tree/master]
-* Lighthouse[http://bahuvrihi.lighthouseapp.com/projects/21202-configurable/tickets?q=state%3Aopen]
 * {Google Group}[http://groups.google.com/group/ruby-on-tap]
 
-== Usage
+==== Minimal Example
 
-Use the config method to declare class configurations.  A block may be provided
-to validate inputs, and many standard validations are available through the 'c'
-method (an alias for the {Validation}[link:classes/Configurable/Validation.html]
-module).
+Include Configurable and declare configurations using the config method.
+Configs now have accessors and initialize with the default value.
 
   class ConfigClass
     include Configurable
+    config :key, 'default', :short => 'k'   # a sample config
+  end
+
+  c = ConfigClass.new
+  c.key                   # => 'default'
+  c.key = 'new value'
+  c.config[:key]          # => 'new value'
+
+Use a ConfigParser to parse configurations from the command line. Non-class
+options may be defined with (mostly) the same syntax as {OptionParser}[http://www.ruby-doc.org/core/classes/OptionParser.html]:
+
+  parser = ConfigParser.new
+  
+  # add class configurations
+  parser.add(ConfigClass.configurations)
+  
+  # define an option a-la OptionParser
+  parser.on '-s', '--long ARGUMENT', 'description' do |value|
+    parser[:long] = value
+  end
+  
+  parser.parse "one two --key value -s VALUE three"  
+  # => ['one', 'two', 'three']
+  
+  parser.config                             
+  # => {
+  # :key => 'value',
+  # :long => 'VALUE'
+  # }
+  
+  "\n" + parser.to_s
+  # => %Q{
+  #    -k, --key KEY                    a sample config
+  #    -s, --long ARGUMENT              description
+  # }
 
-    config :key, 'default', :short => 'k'   # a simple config with short
-    config :flag, false, &c.flag            # a flag config
-    config :switch, false, &c.switch        # a --[no-]switch config
-    config :num, 10, &c.integer             # integer only
-    config :range, 1..10, &c.range          # range only
-    config :upcase, 'default' do |value|    # custom transformation
+== Usage
+
+The config method is used to declare class configurations. A block may be
+provided to validate/transform inputs; many standard validations are available
+through the 'c' method (an alias for the
+{Validation}[link:classes/Configurable/Validation.html] module).
+
+  class ConfigClass
+    include Configurable
+    
+    # basic #
+    
+    config :key, 'default'                    # a simple config
+    config :flag, false, &c.flag              # a flag config
+    config :switch, false, &c.switch          # a --[no-]switch config
+    config :num, 10, &c.integer               # integer only
+    
+    # fancy #
+    
+    config :range, 1..10, &c.range            # specifies a range
+    config :select, 'a', &c.select('a','b')   # value must be 'a' or 'b'
+    config :list, [], &c.list                 # allows a list of entries
+    
+    # custom #
+    
+    config :upcase, 'default' do |value|      # custom transformation
       value.upcase
     end
-
-    def initialize(overrides={})
-      initialize_config(overrides)
+    
+    config :alt, 'default',                   # alternative flags
+      :short => 's',
+      :long => 'long',
+      :arg_name => 'CUSTOM'
+    
+    # Initializes a new instance, setting the overriding configs.
+    def initialize(config={})
+      initialize_config(config)
     end
   end
   
-A ConfigParser can parse configurations from command line arguments, and turn
-them into a documented help string:
+ConfigParser uses the config declarations to parse configurations and to make
+a documented help string:
 
   parser = ConfigParser.new
   parser.add(ConfigClass.configurations)
   
-  parser.parse "one two --key=value --flag --no-switch --num 8 --range a..z three"  
-  # => ['one', 'two', 'three']
+  parser.parse "a b --key=value --flag --no-switch --num 8 c"  
+  # => ['a', 'b', 'c']
   
   parser.config  
   # => {
@@ -55,40 +113,49 @@ them into a documented help string:
   # :flag => true,
   # :switch => false,
   # :num => '8',
-  # :range => 'a..z',
-  # :upcase => 'default'
+  # :range => 1..10,
+  # :select => 'a',
+  # :list => [],
+  # :upcase => 'default',
+  # :alt => 'default'
   # }
   
   "\n" + parser.to_s
   # => %Q{
-  #    -k, --key KEY                    a simple config with short
+  #        --key KEY                    a simple config
   #        --flag                       a flag config
   #        --[no-]switch                a --[no-]switch config
   #        --num NUM                    integer only
-  #        --range RANGE                range only
+  #        --range RANGE                specifies a range
+  #        --select SELECT              value must be 'a' or 'b'
+  #        --list LIST                  allows a list of entries
   #        --upcase UPCASE              custom transformation
+  #    -s, --long CUSTOM                alternative flags
   # }
 
 Configurable classes typically call initialize_config to set configurations
 during initialization. The validation/transformation blocks are called as
-configurations are set.  Notice how the :range and :upcase values have been
-transformed from the input config.
+configurations are set. Notice how the :num and :upcase configs are translated
+on the instance:
   
   c = ConfigClass.new(parser.config)
   c.config.to_hash      
   # => {
   # :key => 'value',
-  # :flag => true,            
-  # :switch => false,         
-  # :num => 8,
-  # :range => 'a'..'z',       # notice these values
-  # :upcase => 'DEFAULT'      # have been transformed
+  # :flag => true,
+  # :switch => false,
+  # :num => 8,                    # no longer a string
+  # :range => 1..10,
+  # :select => 'a',
+  # :list => [],
+  # :upcase => 'DEFAULT',         # no longer downcase
+  # :alt => 'default'
   # }
 
 Configurations automatically generate accessors (the blocks are basically
-writer methods), but they are also accessible through the hash-like config
-object.  Configurations are validated every time they are set, regardless of
-whether they are set through an accessor or config.
+writer methods), and may be accessed through the config object. Configurations
+are validated every time they are set, regardless of whether they are set
+through an accessor or config.
   
   c.upcase                    # => 'DEFAULT'
   
@@ -97,6 +164,10 @@ whether they are set through an accessor or config.
 
   c.upcase = 'fiNal Value'
   c.config[:upcase]           # => 'FINAL VALUE'
+  
+  c.select = 'b'              # ok
+  c.select = 'c'              # !> ValidationError
+  c.config[:select] = 'c'     # !> ValidationError
 
 By default config treats string and symbol keys identically, making YAML an
 obvious choice for configuration files.
@@ -108,28 +179,29 @@ obvious choice for configuration files.
   }
   
   c.reconfigure(YAML.load(yaml_str))
-  c.config.to_hash      
+  c.config.to_hash
   # => {
   # :key => 'a new value',
   # :flag => false,
   # :switch => false,
   # :num => 8,
   # :range => 1..100,
-  # :upcase => 'FINAL VALUE'
+  # :select => 'b',
+  # :list => [],
+  # :upcase => 'FINAL VALUE',
+  # :alt => 'default'
   # }
 
 See the Configurable module for more details.
 
 == Installation
 
-Configurable is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:
+Configurable is available as a gem on Gemcutter[http://gemcutter.org/gems/configurable].
 
   % gem install configurable
 
 == Info 
 
-Copyright (c) 2008-2009, Regents of the University of Colorado.
-Developer:: {Simon Chiang}[http://bahuvrihi.wordpress.com], {Biomolecular Structure Program}[http://biomol.uchsc.edu/], {Hansen Lab}[http://hsc-proteomics.uchsc.edu/hansenlab/] 
-Support:: CU Denver School of Medicine Deans Academic Enrichment Fund
+Developer:: {Simon Chiang}[http://bahuvrihi.wordpress.com]
 License:: {MIT-Style}[link:files/MIT-LICENSE.html]
 

data/lib/config_parser.rb

@@ -147,10 +147,36 @@ class ConfigParser
   
       result
     end
+    
+    # Generates a new parser bound to a specific config.  All this really
+    # means is that each time the parser calls parse, configurations will
+    # be added to the config without clearing the config, or adding default
+    # values. This can be useful in signaling situations where a config
+    # needs to be updated multiple times.
+    #
+    #   psr = ConfigParser.bind
+    #   psr.define('a', 'default')
+    #   psr.define('b', 'default')
+    # 
+    #   psr.parse %w{--a value}
+    #   psr.config                       # => {"a" => "value"}
+    # 
+    #   psr.parse %w{--b value}
+    #   psr.config                       # => {"a" => "value", "b" => "value"}
+    #
+    def bind(config={})
+      parser = new(config, :clear_config => false, :add_defaults => false)
+      yield(parser) if block_given?
+      parser
+    end
   end
   
   include Utils
-
+  
+  # Returns an array of the options registered with self, in the order in
+  # which they were added.  Separators are also stored in the registry.
+  attr_reader :registry
+  
   # A hash of (switch, Option) pairs mapping command line
   # switches like '-s' or '--long' to the Option that
   # handles them.
@@ -159,16 +185,29 @@ class ConfigParser
   # The hash receiving configurations produced by parse.
   attr_accessor :config
   
-  # A hash of default configurations merged into config during parse.
-  attr_reader :default_config
-
+  # A hash of default configurations merged into config during parse. These
+  # defaults are defined as options are added to self (via define, add, etc)
+  # and do not need to be manually specified.
+  attr_reader :defaults
+  
+  # A hash of default parsing options that adjust the behavior of parse
+  # (see parse).
+  attr_reader :default_parse_options
+  
   # Initializes a new ConfigParser and passes it to the block, if given.
-  def initialize(config={})
-    @options = []
+  def initialize(config={}, default_parse_options={})
+    @registry = []
     @switches = {}
     @config = config
-    @default_config = {}
-  
+    @defaults = {}
+    @default_parse_options = {
+      :clear_config => true,
+      :add_defaults => true,
+      :ignore_unknown_options => false,
+      :option_break => OPTION_BREAK,
+      :keep_break => false
+    }.merge(default_parse_options)
+
     yield(self) if block_given?
   end
   
@@ -187,24 +226,36 @@ class ConfigParser
   def nested_config
     ConfigParser.nest(config)
   end
-
+  
   # Returns an array of the options registered with self.
   def options
-    @options.select do |opt|
+    @registry.select do |opt|
       opt.kind_of?(Option)
     end
   end
-
+  
   # Adds a separator string to self, used in to_s.
   def separator(str)
-    @options << str
+    @registry << str
   end
 
-  # Registers the option with self by adding opt to options and mapping
-  # the opt switches. Raises an error for conflicting switches.
-  def register(opt)
-    @options << opt unless @options.include?(opt)
-
+  # Registers the option with self by adding opt to options and mapping the
+  # opt switches. Raises an error for conflicting switches.
+  #
+  # If override is specified, options with conflicting switches are removed
+  # and no error is raised.  Note that this may remove multiple options.
+  def register(opt, override=false)
+    if override
+      existing = opt.switches.collect do |switch|
+        @switches.delete(switch)
+      end
+      @registry -= existing
+    end
+    
+    unless @registry.include?(opt)
+      @registry << opt
+    end
+    
     opt.switches.each do |switch|
       case @switches[switch]
       when opt then next
@@ -253,46 +304,12 @@ class ConfigParser
   #   end
   #
   def on(*args, &block)
-    attributes = args.last.kind_of?(Hash) ? args.pop : {}
-    args.each do |arg|
-      # split switch arguments... descriptions
-      # still won't match as a switch even
-      # after a split
-      switch, arg_name = arg.kind_of?(String) ? arg.split(' ', 2) : arg
-      
-      # determine the kind of argument specified
-      key = case switch
-      when SHORT_OPTION then :short
-      when LONG_OPTION  then :long
-      else :desc
-      end
-      
-      # check for conflicts
-      if attributes[key]
-        raise ArgumentError, "conflicting #{key} options: [#{attributes[key].inspect}, #{arg.inspect}]"
-      end
-      
-      # set the option attributes
-      case key
-      when :long, :short
-        attributes[key] = switch
-        attributes[:arg_name] = arg_name if arg_name
-      else
-        attributes[key] = arg
-      end
-    end
-    
-    # check if a switch-style option is specified
-    klass = case
-    when attributes[:long].to_s =~ /^--\[no-\](.*)$/ 
-      attributes[:long] = "--#{$1}"
-      Switch
-    else 
-      Option
-    end
-    
-    # instantiate and register the new option
-    register klass.new(attributes, &block) 
+    register new_option(args, &block)
+  end
+  
+  # Same as on, but overrides options with overlapping switches.
+  def on!(*args, &block)
+    register new_option(args, &block), true
   end
   
   # Defines and registers a config-style option with self.  Define does not
@@ -345,10 +362,10 @@ class ConfigParser
   # key is already set by a different option.
   def define(key, default_value=nil, attributes={})
     # check for conflicts and register
-    if default_config.has_key?(key)
+    if defaults.has_key?(key)
       raise ArgumentError, "already set by a different option: #{key.inspect}"
     end
-    default_config[key] = default_value
+    defaults[key] = default_value
     
     # ensure setup does not modifiy input attributes
     attributes = attributes.dup
@@ -370,8 +387,7 @@ class ConfigParser
   end
   
   # Adds a hash of delegates (for example the configurations for a Configurable
-  # class) to self.  Delegates will be sorted by their :declaration_order
-  # attribute, then added like:
+  # class) to self.  Configs are added like:
   #
   #   define(key, delegate.default, delegate.attributes)
   #
@@ -379,16 +395,18 @@ class ConfigParser
   #
   # When you nest Configurable classes, a special syntax is necessary to
   # specify nested configurations in a flat format compatible with the
-  # command line.  As such, nested delegates, ie delegates with a 
-  # DelegateHash as a default value, are recursively added with their
-  # key as a prefix.  For instance:
-  #
-  #   delegate_hash = DelegateHash.new(:key => Delegate.new(:reader))
-  #   delegates = {}
-  #   delegates[:nest] = Delegate.new(:reader, :writer=, delegate_hash)
+  # command line.  As such, nested delegates are recursively added with
+  # their key as a prefix.  For instance:
   #
+  #   class NestClass
+  #     include Configurable
+  #     nest :nest do
+  #       config :key, 'value'
+  #     end
+  #   end
+  #  
   #   psr = ConfigParser.new
-  #   psr.add(delegates)
+  #   psr.add(NestClass.configurations)
   #   psr.parse('--nest:key value')
   #
   #   psr.config                 # => {'nest:key' => 'value'}
@@ -402,14 +420,14 @@ class ConfigParser
   def add(delegates, nesting=nil)
     delegates.each_pair do |key, delegate|
       key = nesting ? "#{nesting}:#{key}" : key
-      default = delegate.default(false)
       
-      if delegate.is_nest?
-        unless delegate[:type] == :hidden
-          add(default.delegates, key)
-        end
+      case delegate[:type]
+      when :hidden
+        next
+      when :nest
+        add(delegate.nest_class.configurations, key)
       else
-        define(key, default, delegate.attributes)
+        define(key, delegate.default, delegate.attributes)
       end
     end
   end
@@ -432,63 +450,108 @@ class ConfigParser
   
   # Same as parse, but removes parsed args from argv.
   def parse!(argv=ARGV, options={})
-    options = {
-      :clear_config => true,
-      :add_defaults => true,
-      :ignore_unknown_options => false
-    }.merge(options)
-    
-    config.clear if options[:clear_config]
     argv = Shellwords.shellwords(argv) if argv.kind_of?(String)
+    
     args = []
+    remainder = scan(argv, options) {|arg| args << arg}
+    args.concat(remainder)
+    argv.replace(args)
+    
+    argv
+  end
+  
+  def scan(argv=ARGV, options={})
+    options = default_parse_options.merge(options)
+    config.clear if options[:clear_config]
     
+    option_break = options[:option_break]
     while !argv.empty?
       arg = argv.shift
   
       # determine if the arg is an option
       unless arg.kind_of?(String) && arg[0] == ?-
-        args << arg
+        yield(arg)
         next
       end
       
       # add the remaining args and break
       # for the option break
-      if arg == OPTION_BREAK
-        args.concat(argv)
+      if option_break === arg
+        argv.unshift(arg) if options[:keep_break]
         break
       end
   
       # split the arg...
       # switch= $1
-      # value = $4 || $3 (if arg matches SHORT_OPTION, value is $4 or $3 otherwise)
+      # value = $2
       arg =~ LONG_OPTION || arg =~ SHORT_OPTION || arg =~ ALT_SHORT_OPTION 
   
       # lookup the option
       unless option = @switches[$1]
-        if options[:ignore_unknown_options]
-          args << arg
-          next
-        end
-        
-        raise "unknown option: #{$1}"
+        raise "unknown option: #{$1 || arg}"
       end
   
-      option.parse($1, $4 || $3, argv)
+      option.parse($1, $2, argv)
     end
     
-    default_config.each_pair do |key, default|
+    defaults.each_pair do |key, default|
       config[key] = default unless config.has_key?(key)
     end if options[:add_defaults]
     
-    argv.replace(args)
     argv
   end
   
   # Converts the options and separators in self into a help string suitable for
   # display on the command line.
   def to_s
-    @options.collect do |option|
+    @registry.collect do |option|
       option.to_s.rstrip
     end.join("\n") + "\n"
   end
+  
+  protected
+  
+  # helper to parse an option from an argv.  new_option is used
+  # by on and on! to generate options
+  def new_option(argv, &block) # :nodoc:
+    attributes = argv.last.kind_of?(Hash) ? argv.pop : {}
+    argv.each do |arg|
+      # split switch arguments... descriptions
+      # still won't match as a switch even
+      # after a split
+      switch, arg_name = arg.kind_of?(String) ? arg.split(' ', 2) : arg
+      
+      # determine the kind of argument specified
+      key = case switch
+      when SHORT_OPTION then :short
+      when LONG_OPTION  then :long
+      else :desc
+      end
+      
+      # check for conflicts
+      if attributes[key]
+        raise ArgumentError, "conflicting #{key} options: [#{attributes[key].inspect}, #{arg.inspect}]"
+      end
+      
+      # set the option attributes
+      case key
+      when :long, :short
+        attributes[key] = switch
+        attributes[:arg_name] = arg_name if arg_name
+      else
+        attributes[key] = arg
+      end
+    end
+    
+    # check if a switch-style option is specified
+    klass = case
+    when attributes[:long].to_s =~ /^--\[no-\](.*)$/ 
+      attributes[:long] = "--#{$1}"
+      Switch
+    else 
+      Option
+    end
+    
+    klass.new(attributes, &block)
+  end
 end