configurable 0.4.2 → 0.5.0

data/History

@@ -1,3 +1,21 @@
+== 0.5.0 / 2009-05-25
+
+* fixed io validation to not duplicate IOs
+* fixed :hidden type for nested configurations
+* open_io now returns block result
+* updated Validation parsing of strings into ranges
+* DelegateHash now has the ability to rebind a receiver
+* list validation now accepts validation block
+* added api validation
+* configs may now be specified in modules and included
+  into classes
+* ConfigParser can now ignore unknown options
+* converted num to numeric in Validation (for consistency)
+* changed 'values' to 'options' in select and list_select
+* expanded io/open_io to allow integer file descriptors
+* reworked mapping in DelegateHash to respect indifferent
+  access
+
 == 0.4.2 / 2009-03-30
 
 * set delegate default no longer freezes value

data/lib/config_parser.rb

@@ -156,22 +156,32 @@ class ConfigParser
   # handles them.
   attr_reader :switches
   
-  # The most recent hash of configurations produced by parse.
-  attr_reader :config
+  # The hash receiving configurations produced by parse.
+  attr_accessor :config
   
-  # A hash of default configurations merged into parsed configs.
+  # A hash of default configurations merged into config during parse.
   attr_reader :default_config
 
   # Initializes a new ConfigParser and passes it to the block, if given.
-  def initialize
+  def initialize(config={})
     @options = []
     @switches = {}
-    @config = {}
+    @config = config
     @default_config = {}
   
     yield(self) if block_given?
   end
   
+  # Returns the config value for key.
+  def [](key)
+    config[key]
+  end
+  
+  # Sets the config value for key.
+  def []=(key, value)
+    config[key] = value
+  end
+  
   # Returns the nested form of config (see ConfigParser.nest).  Primarily
   # useful when nested configurations have been added with add.
   def nested_config
@@ -395,7 +405,9 @@ class ConfigParser
       default = delegate.default(false)
       
       if delegate.is_nest?
-        add(default.delegates, key)
+        unless delegate[:type] == :hidden
+          add(default.delegates, key)
+        end
       else
         define(key, default, delegate.attributes)
       end
@@ -407,12 +419,27 @@ class ConfigParser
   # string argv is provided, it will be splits into an array using 
   # Shellwords.
   #
-  # A config may be provided to receive configurations; it will be set
-  # as self.config.
+  # ==== Options
   #
-  def parse(argv=ARGV, config={}, merge_default=true)
-    @config = config
-    argv = argv.kind_of?(String) ? Shellwords.shellwords(argv) : argv.dup
+  # 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)
+  #
+  def parse(argv=ARGV, options={})
+    argv = argv.dup unless argv.kind_of?(String)
+    parse!(argv, options)
+  end
+  
+  # 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 = []
     
     while !argv.empty?
@@ -438,6 +465,11 @@ class ConfigParser
   
       # lookup the option
       unless option = @switches[$1]
+        if options[:ignore_unknown_options]
+          args << arg
+          next
+        end
+        
         raise "unknown option: #{$1}"
       end
   
@@ -446,15 +478,10 @@ class ConfigParser
     
     default_config.each_pair do |key, default|
       config[key] = default unless config.has_key?(key)
-    end if merge_default
+    end if options[:add_defaults]
     
-    args
-  end
-  
-  # Same as parse, but removes parsed args from argv.
-  def parse!(argv=ARGV, config={}, merge_default=true)
-    result = parse(argv, config, merge_default)
-    argv.kind_of?(Array) ? argv.replace(result) : result
+    argv.replace(args)
+    argv
   end
   
   # Converts the options and separators in self into a help string suitable for

data/lib/configurable.rb

@@ -1,4 +1,4 @@
-require 'configurable/class_methods'
+require 'configurable/module_methods'
 
 # Configurable enables the specification of configurations within a class 
 # definition.
@@ -138,11 +138,6 @@ require 'configurable/class_methods'
 #
 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 DelegateHash bound to self
   attr_reader :config
@@ -176,7 +171,7 @@ module Configurable
   
   # Opens the file specified by io and yield it to the block.  If io is an
   # IO, it will be yielded immediately, and the mode is ignored.  Nil io are
-  # simply ignored.  The input io is always returned.
+  # simply ignored.
   #
   # === Usage
   #
@@ -202,10 +197,14 @@ module Configurable
       dir = File.dirname(io)
       FileUtils.mkdir_p(dir) unless File.directory?(dir)
       File.open(io, mode) {|file| yield(file) }
-    when nil
+    when Integer
+      # note this does not close the io because, as far as I understand, 
+      # valid integer file descriptors point to files that are already
+      # open and presumably managed elsewhere
+      yield IO.open(io, mode)
+    when nil then nil
     else yield(io)
     end
-    io
   end
 
   # Initializes config. Default config values 

data/lib/configurable/class_methods.rb

@@ -15,15 +15,6 @@ module Configurable
     # A hash of (key, Delegate) pairs defining the class configurations.
     attr_reader :configurations
 
-    def self.extended(base) # :nodoc:
-      unless base.instance_variable_defined?(:@source_file)
-        caller[2] =~ Lazydoc::CALLER_REGEXP
-        base.instance_variable_set(:@source_file, File.expand_path($1)) 
-      end
-      
-      base.send(:initialize_configurations).extend(IndifferentAccess)
-    end
-
     def inherited(child) # :nodoc:
       unless child.instance_variable_defined?(:@source_file)
         caller[0] =~ Lazydoc::CALLER_REGEXP
@@ -40,23 +31,23 @@ module Configurable
     end
     
     # Parses configurations from argv in a non-destructive manner by generating
-    # a ConfigParser using the configurations for self.  Parsed configs are 
-    # added to config (note that you must keep a separate reference to 
-    # config as it is not returned by parse).  The parser will is yielded to the
-    # block, if given, to register additonal options.  Returns an array of the 
-    # arguments that remain after parsing.
+    # a ConfigParser using the configurations for self.  Returns an array like
+    # [args, config] where the args are the arguments that remain after parsing,
+    # and config is a hash of the parsed configs. The parser will is yielded to
+    # the block, if given, to register additonal options.  
     #
     # See ConfigParser#parse for more information.
-    def parse(argv=ARGV, config={})
-      ConfigParser.new do |parser|
-        parser.add(configurations)
-        yield(parser) if block_given?
-      end.parse(argv, config)
+    def parse(argv=ARGV, options={}) # :yields: parser
+      parse!(argv.dup, options)
     end
     
     # Same as parse, but removes parsed args from argv.
-    def parse!(argv=ARGV, config={})
-      argv.replace(parse(argv, config))
+    def parse!(argv=ARGV, options={})
+      parser = ConfigParser.new
+      parser.add(configurations)
+      
+      args = parser.parse!(argv, options)
+      [args, parser.config]
     end
     
     protected
@@ -302,7 +293,14 @@ module Configurable
       else
         key.to_s.capitalize
       end
-      const_set(const_name, configurable_class) if const_name
+      
+      if const_name
+        # this prevents a warning in cases where the nesting
+        # class defines the configurable_class
+        unless const_defined?(const_name) && const_get(const_name) == configurable_class
+          const_set(const_name, configurable_class)
+        end
+      end
       
       # define instance reader
       instance_reader = define_attribute_method(:instance_reader, attributes, key) do |attribute|

data/lib/configurable/delegate_hash.rb

@@ -60,10 +60,10 @@ module Configurable
     # Binds self to the specified receiver.  Delegate values are removed from
     # store and sent to their writer on receiver.  If the store has no value
     # for a delegate key, the delegate default value will be used.
-    def bind(receiver)
+    def bind(receiver, rebind=false)
       raise ArgumentError, "receiver cannot be nil" if receiver == nil
       
-      if bound?
+      if bound? && !rebind
         if @receiver == receiver
           return(self)
         else
@@ -152,10 +152,18 @@ module Configurable
 
     # Returns self as a hash.  Any DelegateHash values are recursively
     # hashified, to account for nesting.
-    def to_hash
+    def to_hash(&block)
       hash = {}
       each_pair do |key, value|
-        hash[key] = value.kind_of?(DelegateHash) ? value.to_hash : value
+        if value.kind_of?(DelegateHash)
+          value = value.to_hash(&block)
+        end
+        
+        if block_given?
+          yield(hash, key, value)
+        else
+          hash[key] = value
+        end
       end
       hash
     end
@@ -178,15 +186,30 @@ module Configurable
     
     # helper to map delegate values from source to the receiver
     def map(source) # :nodoc:
+      source_values = {}
+      source.each_key do |key|
+        if delegate = delegates[key]
+          if source_values.has_key?(delegate)
+            key = delegates.keys.find {|k| delegates[k] == delegate }
+            raise "multiple values mapped to #{key.inspect}"
+          end
+          
+          source_values[delegate] = source.delete(key)
+        end
+      end
+      
       delegates.each_pair do |key, delegate|
         # map the value; if no value is set in the source then use the 
         # delegate default.  if map_default is false, then simply skip... 
         # this ensures each config is initialized to a value when bound
         # UNLESS map_default is set (indicating manual initialization)
         value = case
-        when source.has_key?(key) then source.delete(key)
-        when delegate[:set_default, true] then delegate.default
-        else next
+        when source_values.has_key?(delegate)
+          source_values[delegate]
+        when delegate[:set_default, true]
+          delegate.default
+        else
+          next
         end
         
         receiver.send(delegate.writer, value)

data/lib/configurable/module_methods.rb

@@ -0,0 +1,30 @@
+require 'configurable/class_methods'
+
+module Configurable
+  module ModuleMethods
+    
+    # Extends including classes with Configurable::ClassMethods
+    def included(mod)
+      mod.extend ClassMethods
+      mod.extend ModuleMethods unless mod.kind_of?(Class)
+      
+      unless mod.instance_variable_defined?(:@source_file)
+        caller[1] =~ Lazydoc::CALLER_REGEXP
+        mod.instance_variable_set(:@source_file, File.expand_path($1)) 
+      end
+      
+      unless mod.instance_variable_defined?(:@configurations)
+        mod.send(:initialize_configurations).extend(IndifferentAccess)
+      end
+      
+      # add module configurations      
+      configurations.each_pair do |key, config| 
+        mod.configurations[key] = config.dup
+      end unless self == Configurable
+      
+      super
+    end
+  end
+  
+  extend ModuleMethods
+end

data/lib/configurable/validation.rb

@@ -39,6 +39,18 @@ module Configurable
         end
       end
     end
+    
+    # Raised when validate_api fails.
+    class ApiError < ArgumentError
+      def initialize(input, methods)
+        super case 
+        when methods.empty?
+          "no api specified"
+        else
+          "expected api #{methods.inspect} for: #{input.inspect}"
+        end
+      end
+    end
 
     module_function
 
@@ -50,12 +62,18 @@ module Configurable
     end
     
     # Registers the default attributes of the source as the attributes
-    # of the target.  Attributes are duplicated so they may be modifed.
-    def register_as(source, target)
-      DEFAULT_ATTRIBUTES[target] = DEFAULT_ATTRIBUTES[source].dup
+    # of the target.  Overridding or additional attributes are merged
+    # to the defaults.
+    def register_as(source, target, attributes={})
+      DEFAULT_ATTRIBUTES[target] = DEFAULT_ATTRIBUTES[source].dup.merge!(attributes)
       target
     end
     
+    # Returns the attributes registered to the block.
+    def attributes(block)
+      DEFAULT_ATTRIBUTES[block] || {}
+    end
+    
     # Returns input if it matches any of the validations as in would in a case
     # statement.  Raises a ValidationError otherwise.  For example:
     #
@@ -69,9 +87,10 @@ module Configurable
     #   end
     #
     # A block may be provided to handle invalid inputs; if provided it will be
-    # called and a ValidationError will not be raised.  Note the validations
-    # input must be an Array or nil; validate will raise an ArgumentError
-    # otherwise.  All inputs are considered VALID if validations == nil.
+    # called with the input and a ValidationError will not be raised unless the
+    # block returns false.  Note the validations input must be an Array or nil;
+    # validate will raise an ArgumentError otherwise.  All inputs are
+    # considered VALID if validations == nil.
     def validate(input, validations)
       case validations
       when Array
@@ -87,10 +106,38 @@ module Configurable
         end
     
       when nil then input
-      else raise ArgumentError, "validations must be nil, or an array of valid inputs"
+      else raise ArgumentError, "validations must be an array of valid inputs or nil"
       end
     end
     
+    # Returns input if it responds to all of the specified methods.  Raises an
+    # ApiError otherwise.  For example:
+    #
+    #   validate_api(10, [:to_s, :to_f])             # => 10
+    #   validate_api(Object.new, [:to_s, :to_f])     # !> ApiError
+    #
+    # A block may be provided to handle invalid inputs; if provided it will be
+    # called with the input and an ApiError will not be raised unless the 
+    # block returns false.  Note the methods input must be an Array or nil;
+    # validate_api will raise an ArgumentError otherwise.  All inputs are
+    # considered VALID if methods == nil.
+    def validate_api(input, methods)
+      case methods
+      when Array
+        unless methods.all? {|m| input.respond_to?(m) }
+          if block_given? && yield(input)
+            input
+          else
+            raise ApiError.new(input, methods)
+          end
+        end
+      when nil
+      else raise ArgumentError, "methods must be an array or nil"
+      end
+      
+      input
+    end
+    
     # Helper to load the input into a valid object.  If a valid object is not
     # loaded as YAML, or if an error occurs, the original input is returned.
     def load_if_yaml(input, *validations)
@@ -110,7 +157,15 @@ module Configurable
     def check(*validations)
       lambda {|input| validate(input, validations) }
     end
-
+    
+    # Returns a block that calls validate_api using the block input
+    # and methods.
+    def api(*methods)
+      lambda do |input|
+        validate_api(input, methods)
+      end
+    end
+    
     # Returns a block that loads input strings as YAML, then
     # calls validate with the result and validations. Non-string 
     # inputs are validated directly.
@@ -266,7 +321,20 @@ module Configurable
     #   list.call('str')          # => ValidationError
     #   list.call(nil)            # => ValidationError
     #
-    def list(); LIST; end
+    def list(&validation)
+      return LIST unless validation
+      
+      block = lambda do |input|
+        args = validate(input, [Array]).collect do |arg| 
+          arg.kind_of?(String) ? YAML.load(arg) : arg
+        end
+        args.collect! {|arg| validation.call(arg) }
+        args
+      end
+      
+      register_as(LIST, block, :validation => attributes(validation))
+    end
+    
     list_block = lambda do |input|
       validate(input, [Array]).collect do |arg| 
         arg.kind_of?(String) ? YAML.load(arg) : arg
@@ -355,26 +423,26 @@ module Configurable
     # Returns a block that checks the input is a number.
     # String inputs are loaded as yaml first.
     #
-    #   num.class               # => Proc
-    #   num.call(1.1)           # => 1.1
-    #   num.call(1)             # => 1
-    #   num.call(1e6)           # => 1e6
-    #   num.call('1.1')         # => 1.1
-    #   num.call('1.0e+6')      # => 1e6
-    #   num.call(nil)           # => ValidationError
-    #   num.call('str')         # => ValidationError
+    #   numeric.class               # => Proc
+    #   numeric.call(1.1)           # => 1.1
+    #   numeric.call(1)             # => 1
+    #   numeric.call(1e6)           # => 1e6
+    #   numeric.call('1.1')         # => 1.1
+    #   numeric.call('1.0e+6')      # => 1e6
+    #   numeric.call(nil)           # => ValidationError
+    #   numeric.call('str')         # => ValidationError
     #
-    def num(); NUMERIC; end
+    def numeric(); NUMERIC; end
     
-    # default attributes {:type => :num, :example => "2, 2.2, 2.0e+2"}
+    # default attributes {:type => :numeric, :example => "2, 2.2, 2.0e+2"}
     NUMERIC = yaml(Numeric)
-    register NUMERIC, :type => :num, :example => "2, 2.2, 2.0e+2"
+    register NUMERIC, :type => :numeric, :example => "2, 2.2, 2.0e+2"
     
-    # Same as num but allows nil:
+    # Same as numeric but allows nil:
     #
-    #   num_or_nil.call('~')    # => nil
-    #   num_or_nil.call(nil)    # => nil
-    def num_or_nil(); NUMERIC_OR_NIL; end
+    #   numeric_or_nil.call('~')    # => nil
+    #   numeric_or_nil.call(nil)    # => nil
+    def numeric_or_nil(); NUMERIC_OR_NIL; end
     
     NUMERIC_OR_NIL = yaml(Numeric, nil)
     register_as NUMERIC, NUMERIC_OR_NIL
@@ -429,9 +497,8 @@ module Configurable
     register_as REGEXP, REGEXP_OR_NIL
 
     # Returns a block that checks the input is a range. String inputs are
-    # loaded as yaml; if the result is still a string, it is split into a
-    # beginning and end, if possible, and each part is loaded as yaml
-    # before being used to construct a Range.
+    # loaded as yaml (a '!ruby/range' prefix is added before loading if
+    # if it is not specified).
     #
     #   range.class               # => Proc
     #   range.call(1..10)         # => 1..10
@@ -448,13 +515,10 @@ module Configurable
     def range(); RANGE; end
     range_block = lambda do |input|
       if input.kind_of?(String)
+        input = "!ruby/range #{input}" unless input =~ /\A\s*!ruby\/range\s/
         input = load_if_yaml(input, Range)
       end
       
-      if input.kind_of?(String) && input =~ /^([^.]+)(\.{2,3})([^.]+)$/
-        input = Range.new(YAML.load($1), YAML.load($3), $2.length == 3) 
-      end
-      
       validate(input, [Range])
     end
     
@@ -533,8 +597,8 @@ module Configurable
     TIME_OR_NIL = time_or_nil_block
     register_as TIME, TIME_OR_NIL
     
-    # Returns a block that only allows the specified values.  Select can take
-    # a block that will validate each individual value.
+    # Returns a block that only allows the specified options.  Select can take
+    # a block that will validate the input individual value.
     #
     #   s = select(1,2,3, &integer)
     #   s.class                      # => Proc
@@ -547,20 +611,23 @@ module Configurable
     #
     # The select block is registered with these default attributes: 
     #
-    #  {:type => :select, :values => values}
+    #  {:type => :select, :options => options}
     #
-    def select(*values, &validation)
+    def select(*options, &validation)
       block = lambda do |input|
         input = validation.call(input) if validation
-        validate(input, values)
+        validate(input, options)
       end
       
-      register(block, :type => :select, :values => values)
+      register(block, 
+        :type => :select, 
+        :options => options,
+        :validation => attributes(validation))
     end
     
     # Returns a block that checks the input is an array, and that each member
-    # of the array is one of the specified values.  A block may be provided
-    # to validate each individual value.
+    # of the array is included in options.  A block may be provided to validate
+    # the individual values.
     #
     #   s = list_select(1,2,3, &integer)
     #   s.class                      # => Proc
@@ -575,27 +642,31 @@ module Configurable
     #
     # The list_select block is registered with these default attributes: 
     #
-    #  {:type => :list_select, :values => values, :split => ','}
+    #  {:type => :list_select, :options => options, :split => ','}
     #
-    def list_select(*values, &validation)
+    def list_select(*options, &validation)
       block = lambda do |input|
         args = validate(input, [Array])
         args.collect! {|arg| validation.call(arg) } if validation
-        args.each {|arg| validate(arg, values) }
+        args.each {|arg| validate(arg, options) }
       end
       
-      register(block, :type => :list_select, :values => values, :split => ',')
+      register(block, 
+        :type => :list_select, 
+        :options => options, 
+        :split => ',',
+        :validation => attributes(validation))
     end
     
-    # Returns a block validating the input is an IO or a string.  String inputs
-    # are expected to be filepaths, but io does not open a file immediately.
+    # Returns a block validating the input is an IO, a string, or an integer.
+    # String inputs are expected to be filepaths and integer inputs are expected
+    # to be valid file descriptors, but io does not open an IO immediately.
     #
     #   io.class                     # => Proc
     #   io.call($stdout)             # => $stdout
     #   io.call('/path/to/file')     # => '/path/to/file'
-    #
+    #   io.call(1)                   # => 1
     #   io.call(nil)                 # => ValidationError
-    #   io.call(10)                  # => ValidationError
     #
     # An IO api can be specified to allow other objects to be validated.  This
     # is useful for duck-typing an IO when a known subset of methods are needed.
@@ -603,15 +674,18 @@ module Configurable
     #   array_io = io(:<<)
     #   array_io.call($stdout)       # => $stdout
     #   array_io.call([])            # => []
-    #   array_io.call(nil)           # => ValidationError
+    #   array_io.call(nil)           # => ApiError
     #
+    # Note that by default io configs will not be duplicated (duplicate IOs
+    # flush separately, and this can result in disorder.  see
+    # http://gist.github.com/88808).
     def io(*api)
       if api.empty?
         IO_OR_STRING
       else
         block = lambda do |input|
-          validate(input, [IO, String]) do
-            api.all? {|m| input.respond_to?(m) }
+          validate(input, [IO, String, Integer]) do
+            validate_api(input, api)
           end
         end
         
@@ -619,9 +693,9 @@ module Configurable
       end
     end
     
-    # default attributes {:type => :io, :example => "/path/to/file"}
-    IO_OR_STRING = check(IO, String)
-    register IO_OR_STRING, :type => :io, :example => "/path/to/file"
+    # default attributes {:type => :io, :duplicate_default => false, :example => "/path/to/file"}
+    IO_OR_STRING = check(IO, String, Integer)
+    register IO_OR_STRING, :type => :io, :duplicate_default => false, :example => "/path/to/file"
     
     # Same as io but allows nil:
     #
@@ -632,8 +706,8 @@ module Configurable
         IO_STRING_OR_NIL
       else
         block = lambda do |input|
-          validate(input, [IO, String, nil]) do
-            api.all? {|m| input.respond_to?(m) }
+          validate(input, [IO, String, Integer, nil]) do
+            validate_api(input, api)
           end
         end
         
@@ -641,7 +715,7 @@ module Configurable
       end  
     end
     
-    IO_STRING_OR_NIL = check(IO, String, nil)
+    IO_STRING_OR_NIL = check(IO, String, Integer, nil)
     register_as IO_OR_STRING, IO_STRING_OR_NIL
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: configurable
 version: !ruby/object:Gem::Version 
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors: 
 - Simon Chiang
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-30 00:00:00 -06:00
+date: 2009-05-25 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -20,7 +20,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.3.1
+        version: 0.9.0
     version: 
 description: 
 email: simon.a.chiang@gmail.com
@@ -45,6 +45,7 @@ files:
 - lib/configurable/delegate.rb
 - lib/configurable/delegate_hash.rb
 - lib/configurable/indifferent_access.rb
+- lib/configurable/module_methods.rb
 - lib/configurable/validation.rb
 - lib/configurable/utils.rb
 - MIT-LICENSE