configurable 0.4.1 → 0.4.2

data/History

@@ -1,3 +1,12 @@
+== 0.4.2 / 2009-03-30
+
+* set delegate default no longer freezes value
+* added :duplicate_default attribute to turn off default
+  value duplication
+* standardized formatting of argument names
+* added select and list_select validations
+* added io validation + open_io method
+
 == 0.4.1 / 2009-03-23
 
 * Simplified internal API for nesting (removed initialize_<key>)

data/lib/config_parser.rb

@@ -346,14 +346,13 @@ class ConfigParser
     block = case attributes[:type]
     when :switch then setup_switch(key, default_value, attributes)
     when :flag   then setup_flag(key, default_value, attributes)
-    when :list   then setup_list(key, attributes)
+    when :list, :list_select then setup_list(key, attributes)
     when :hidden then return nil
-    when nil     then setup_option(key, attributes)
     else
       if respond_to?("setup_#{attributes[:type]}")
         send("setup_#{attributes[:type]}", key, default_value, attributes)
       else
-        raise ArgumentError, "unsupported type: #{attributes[:type]}"
+        setup_option(key, attributes)
       end
     end
     

data/lib/config_parser/utils.rb

@@ -120,19 +120,15 @@ class ConfigParser
     # Attributes:
     #
     #   :long      the long key ("--key")
-    #   :arg_name  the argument name ("KEY" or "A,B,C" for a comma split) 
+    #   :arg_name  the argument name ("KEY")
     #   :split     the split character
     #
     def setup_list(key, attributes={})
       attributes[:long] ||= "--#{key}"
+      attributes[:long].to_s =~ /^(--)?(.*)$/ 
+      attributes[:arg_name] ||= $2.upcase
       
-      if split = attributes[:split]
-        attributes[:arg_name] ||= %w{A B C}.join(split)
-      else
-        attributes[:long].to_s =~ /^(--)?(.*)$/ 
-        attributes[:arg_name] ||= $2.upcase
-      end
-      
+      split = attributes[:split]
       n = attributes[:n]
       
       lambda do |value|

data/lib/configurable.rb

@@ -173,6 +173,40 @@ module Configurable
   end
 
   protected
+  
+  # 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.
+  #
+  # === Usage
+  #
+  # open_io is used to compliment the io validation, to ensure that if a file
+  # is specified, it will be closed.
+  #
+  #   class IoSample
+  #     include Configurable
+  #     config :output, $stdout, &c.io    # can be an io or filepath
+  #
+  #     def say_hello
+  #       open_io(output, 'w') do |io|
+  #         io << 'hello!'
+  #       end
+  #     end
+  #   end
+  #
+  # In short, this method provides a way to responsibly handle IO and file
+  # configurations. 
+  def open_io(io, mode='r')
+    case io
+    when String
+      dir = File.dirname(io)
+      FileUtils.mkdir_p(dir) unless File.directory?(dir)
+      File.open(io, mode) {|file| yield(file) }
+    when nil
+    else yield(io)
+    end
+    io
+  end
 
   # Initializes config. Default config values 
   # are overridden as specified by overrides.

data/lib/configurable/delegate.rb

@@ -22,23 +22,25 @@ module Configurable
     # The writer method, by default key=
     attr_reader :writer
 
-    # An hash of metadata for self, used to present the 
-    # delegate in different contexts (ex on the command
-    # line, in a web form, or a desktop app).
+    # An hash of metadata for self, used to present the delegate in different
+    # contexts (ex on the command line, in a web form, or a desktop app).
+    # Note that attributes should be set through []= and not through this
+    # reader.
     attr_reader :attributes
 
     # Initializes a new Delegate with the specified key and default value.
     def initialize(reader, writer="#{reader}=", default=nil, attributes={})
+      @attributes = attributes
+      
       self.default = default
       self.reader = reader
       self.writer = writer
-  
-      @attributes = attributes
     end
     
     # Sets the value of an attribute.
     def []=(key, value)
       attributes[key] = value
+      reset_duplicable if key == :duplicate_default
     end
     
     # Returns the value for the specified attribute, or
@@ -49,13 +51,14 @@ module Configurable
 
     # Sets the default value for self.
     def default=(value)
-      @duplicable = Delegate.duplicable_value?(value)
-      @default = value.freeze
+      @default = value
+      reset_duplicable
     end
 
-    # Returns the default value, or a duplicate of the default
-    # value if specified and the default value is duplicable
-    # (see Delegate.duplicable_value?)
+    # Returns the default value, or a duplicate of the default value if specified.
+    # The default value will not be duplicated unless duplicable (see 
+    # Delegate.duplicable_value?).  Duplication can also be turned off by
+    # specifying self[:duplicate_default] = false.
     def default(duplicate=true)
       duplicate && @duplicable ? @default.dup : @default
     end
@@ -86,5 +89,15 @@ module Configurable
       self.writer == another.writer &&
       self.default(false) == another.default(false)
     end
+    
+    private
+    
+    # resets marker indiciating whether or not a default value is duplicable
+    def reset_duplicable # :nodoc:
+      @duplicable = case attributes[:duplicate_default]
+      when true, nil then Delegate.duplicable_value?(@default)
+      else false
+      end
+    end
   end
 end

data/lib/configurable/validation.rb

@@ -46,6 +46,14 @@ module Configurable
     # in Configurable::DEFAULT_ATTRIBUTES.
     def register(block, attributes)
       DEFAULT_ATTRIBUTES[block] = attributes
+      block
+    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
+      target
     end
     
     # Returns input if it matches any of the validations as in would in a case
@@ -71,9 +79,9 @@ module Configurable
         case input
         when *validations then input
         else 
-          if block_given? 
-            yield(input)
-          else 
+          if block_given? && yield(input)
+            input
+          else
             raise ValidationError.new(input, validations)
           end
         end
@@ -82,7 +90,21 @@ module Configurable
       else raise ArgumentError, "validations must be nil, or an array of valid inputs"
       end
     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)
+      begin
+        yaml = YAML.load(input)
+        case yaml
+        when *validations then yaml
+        else input
+        end
+      rescue(ArgumentError)
+        input
+      end
+    end
+    
     # Returns a block that calls validate using the block input
     # and validations.
     def check(*validations)
@@ -127,8 +149,11 @@ module Configurable
       input = validate(input, [String])
       eval %Q{"#{input}"}
     end
+    
+    # default attributes {:type => :string, :example => "string"}
     STRING = string_validation_block
-
+    register STRING, :type => :string, :example => "string"
+    
     # Same as string but allows nil.  Note the special
     # behavior of the nil string '~' -- rather than
     # being treated as a string, it is processed as nil
@@ -145,8 +170,10 @@ module Configurable
       else eval %Q{"#{input}"}
       end
     end
+    
     STRING_OR_NIL = string_or_nil_validation_block
-
+    register_as STRING, STRING_OR_NIL
+    
     # Returns a block that checks the input is a symbol.
     # String inputs are loaded as yaml first.
     #
@@ -157,15 +184,20 @@ module Configurable
     #   symbol.call('str')        # => ValidationError
     #
     def symbol(); SYMBOL; end
+    
+    # default attributes {:type => :symbol, :example => ":sym"}
     SYMBOL = yaml(Symbol)
-
+    register SYMBOL, :type => :symbol, :example => ":sym"
+    
     # Same as symbol but allows nil:
     #
     #   symbol_or_nil.call('~')   # => nil
     #   symbol_or_nil.call(nil)   # => nil
     def symbol_or_nil(); SYMBOL_OR_NIL; end
+    
     SYMBOL_OR_NIL = yaml(Symbol, nil)
-
+    register_as SYMBOL, SYMBOL_OR_NIL
+    
     # Returns a block that checks the input is true, false or nil.
     # String inputs are loaded as yaml first.
     #
@@ -182,7 +214,10 @@ module Configurable
     #   boolean.call("str")       # => ValidationError
     #
     def boolean(); BOOLEAN; end
+    
+    # default attributes {:type => :boolean, :example => "true, yes"}
     BOOLEAN = yaml(true, false, nil)
+    register BOOLEAN, :type => :boolean, :example => "true, yes"
 
     # Same as boolean.
     def switch(); SWITCH; end
@@ -209,9 +244,9 @@ module Configurable
     #
     def array(); ARRAY; end
     
-    # default attributes {:arg_name => "'[a, b, c]'"}
+    # default attributes {:type => :array, :example => "[a, b, c]"}
     ARRAY = yaml(Array)
-    register ARRAY, :arg_name => "'[a, b, c]'"
+    register ARRAY, :type => :array, :example => "[a, b, c]"
 
     # Same as array but allows nil:
     #
@@ -219,9 +254,8 @@ module Configurable
     #   array_or_nil.call(nil)    # => nil
     def array_or_nil(); ARRAY_OR_NIL; end
     
-    # default attributes {:arg_name => "'[a, b, c]'"}
     ARRAY_OR_NIL = yaml(Array, nil)
-    register ARRAY_OR_NIL, :arg_name => "'[a, b, c]'"
+    register_as ARRAY, ARRAY_OR_NIL
 
     # Returns a block that checks the input is an array,
     # then yamlizes each string value of the array.
@@ -254,9 +288,9 @@ module Configurable
     #
     def hash(); HASH; end
     
-    # default attributes {:arg_name => "'{one: 1, two: 2}'"}
+    # default attributes {:type => :hash, :example => "{one: 1, two: 2}"}
     HASH = yaml(Hash)
-    register HASH, :arg_name => "'{one: 1, two: 2}'"
+    register HASH, :type => :hash, :example => "{one: 1, two: 2}"
 
     # Same as hash but allows nil:
     #
@@ -264,9 +298,8 @@ module Configurable
     #   hash_or_nil.call(nil)          # => nil
     def hash_or_nil(); HASH_OR_NIL; end
     
-    # default attributes {:arg_name => "'{one: 1, two: 2}'"}
     HASH_OR_NIL = yaml(Hash, nil)
-    register HASH_OR_NIL, :arg_name => "'{one: 1, two: 2}'"
+    register_as HASH, HASH_OR_NIL
 
     # Returns a block that checks the input is an integer.
     # String inputs are loaded as yaml first.
@@ -279,15 +312,20 @@ module Configurable
     #   integer.call('str')       # => ValidationError
     #
     def integer(); INTEGER; end
+    
+    # default attributes {:type => :integer, :example => "2"}
     INTEGER = yaml(Integer)
-
+    register INTEGER, :type => :integer, :example => "2"
+    
     # Same as integer but allows nil:
     #
     #   integer_or_nil.call('~')  # => nil
     #   integer_or_nil.call(nil)  # => nil
     def integer_or_nil(); INTEGER_OR_NIL; end
+    
     INTEGER_OR_NIL = yaml(Integer, nil)
-
+    register_as INTEGER, INTEGER_OR_NIL
+    
     # Returns a block that checks the input is a float.
     # String inputs are loaded as yaml first.
     #
@@ -300,14 +338,19 @@ module Configurable
     #   float.call('str')         # => ValidationError
     #
     def float(); FLOAT; end
+    
+    # default attributes {:type => :float, :example => "2.2, 2.0e+2"}
     FLOAT = yaml(Float)
-
+    register FLOAT, :type => :float, :example => "2.2, 2.0e+2"
+    
     # Same as float but allows nil:
     #
     #   float_or_nil.call('~')    # => nil
     #   float_or_nil.call(nil)    # => nil
     def float_or_nil(); FLOAT_OR_NIL; end
+
     FLOAT_OR_NIL = yaml(Float, nil)
+    register_as FLOAT, FLOAT_OR_NIL
 
     # Returns a block that checks the input is a number.
     # String inputs are loaded as yaml first.
@@ -322,14 +365,19 @@ module Configurable
     #   num.call('str')         # => ValidationError
     #
     def num(); NUMERIC; end
+    
+    # default attributes {:type => :num, :example => "2, 2.2, 2.0e+2"}
     NUMERIC = yaml(Numeric)
-
+    register NUMERIC, :type => :num, :example => "2, 2.2, 2.0e+2"
+    
     # Same as num 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 = yaml(Numeric, nil)
+    register_as NUMERIC, NUMERIC_OR_NIL
 
     # Returns a block that checks the input is a regexp. String inputs are
     # loaded as yaml; if the result is not a regexp, it is converted to
@@ -349,10 +397,7 @@ module Configurable
     def regexp(); REGEXP; end
     regexp_block = lambda do |input|
       if input.kind_of?(String)
-        begin
-          input = validate(YAML.load(input), [Regexp]) {|obj| input }
-        rescue(ArgumentError)
-        end
+        input = load_if_yaml(input, Regexp)
       end
       
       if input.kind_of?(String)
@@ -361,7 +406,10 @@ module Configurable
       
       validate(input, [Regexp])
     end
+    
+    # default attributes {:type => :regexp, :example => "/regexp/i"}
     REGEXP = regexp_block
+    register REGEXP, :type => :regexp, :example => "/regexp/i"
 
     # Same as regexp but allows nil. Note the special behavior of the nil
     # string '~' -- rather than being converted to a regexp, it is processed
@@ -376,7 +424,9 @@ module Configurable
       else REGEXP[input]
       end
     end
+    
     REGEXP_OR_NIL = regexp_or_nil_block
+    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
@@ -398,10 +448,7 @@ module Configurable
     def range(); RANGE; end
     range_block = lambda do |input|
       if input.kind_of?(String)
-        begin
-          input = validate(YAML.load(input), [Range]) {|obj| input }
-        rescue(ArgumentError)
-        end
+        input = load_if_yaml(input, Range)
       end
       
       if input.kind_of?(String) && input =~ /^([^.]+)(\.{2,3})([^.]+)$/
@@ -410,8 +457,11 @@ module Configurable
       
       validate(input, [Range])
     end
+    
+    # default attributes {:type => :range, :example => "min..max"}
     RANGE = range_block
-
+    register RANGE, :type => :range, :example => "min..max"
+    
     # Same as range but allows nil:
     #
     #   range_or_nil.call('~')    # => nil
@@ -423,7 +473,9 @@ module Configurable
       else RANGE[input]
       end
     end
+    
     RANGE_OR_NIL = range_or_nil_block
+    register_as RANGE, RANGE_OR_NIL
 
     # Returns a block that checks the input is a Time. String inputs are 
     # loaded using Time.parse and then converted into times.  Parsed times 
@@ -460,8 +512,11 @@ module Configurable
       input = Time.parse(input) if input.kind_of?(String)
       validate(input, [Time])
     end
+    
+    # default attributes {:type => :time, :example => "2008-08-08 08:00:00"}
     TIME = time_block
-
+    register TIME, :type => :time, :example => "2008-08-08 08:00:00"
+    
     # Same as time but allows nil:
     #
     #   time_or_nil.call('~')    # => nil
@@ -474,7 +529,119 @@ module Configurable
       else TIME[input]
       end
     end 
+    
     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.
+    #
+    #   s = select(1,2,3, &integer)
+    #   s.class                      # => Proc
+    #   s.call(1)                    # => 1
+    #   s.call('3')                  # => 3
+    #
+    #   s.call(nil)                  # => ValidationError
+    #   s.call(0)                    # => ValidationError
+    #   s.call('4')                  # => ValidationError
+    #
+    # The select block is registered with these default attributes: 
+    #
+    #  {:type => :select, :values => values}
+    #
+    def select(*values, &validation)
+      block = lambda do |input|
+        input = validation.call(input) if validation
+        validate(input, values)
+      end
+      
+      register(block, :type => :select, :values => values)
+    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.
+    #
+    #   s = list_select(1,2,3, &integer)
+    #   s.class                      # => Proc
+    #   s.call([1])                  # => [1]
+    #   s.call([1, '3'])             # => [1, 3]
+    #   s.call([])                   # => []
+    #
+    #   s.call(1)                    # => ValidationError
+    #   s.call([nil])                # => ValidationError
+    #   s.call([0])                  # => ValidationError
+    #   s.call(['4'])                # => ValidationError
+    #
+    # The list_select block is registered with these default attributes: 
+    #
+    #  {:type => :list_select, :values => values, :split => ','}
+    #
+    def list_select(*values, &validation)
+      block = lambda do |input|
+        args = validate(input, [Array])
+        args.collect! {|arg| validation.call(arg) } if validation
+        args.each {|arg| validate(arg, values) }
+      end
+      
+      register(block, :type => :list_select, :values => values, :split => ',')
+    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.
+    #
+    #   io.class                     # => Proc
+    #   io.call($stdout)             # => $stdout
+    #   io.call('/path/to/file')     # => '/path/to/file'
+    #
+    #   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.
+    #
+    #   array_io = io(:<<)
+    #   array_io.call($stdout)       # => $stdout
+    #   array_io.call([])            # => []
+    #   array_io.call(nil)           # => ValidationError
+    #
+    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) }
+          end
+        end
+        
+        register_as IO_OR_STRING, block
+      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"
+    
+    # Same as io but allows nil:
+    #
+    #   io_or_nil.call(nil)          # => nil
+    #
+    def io_or_nil(*api)
+      if api.empty?
+        IO_STRING_OR_NIL
+      else
+        block = lambda do |input|
+          validate(input, [IO, String, nil]) do
+            api.all? {|m| input.respond_to?(m) }
+          end
+        end
+        
+        register_as IO_STRING_OR_NIL, block
+      end  
+    end
     
+    IO_STRING_OR_NIL = check(IO, String, 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.1
+  version: 0.4.2
 platform: ruby
 authors: 
 - Simon Chiang
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-23 00:00:00 -06:00
+date: 2009-03-30 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency