configurable 0.1.0

data/lib/configurable/delegate.rb

@@ -0,0 +1,75 @@
+module Configurable
+  
+  # Delegates are used by DelegateHash to determine how to map read/write
+  # operations to a receiver.
+  class Delegate
+    class << self
+  
+      # Determines if the value is duplicable.  Non-duplicable 
+      # values include nil, true, false, Symbol, Numeric, and 
+      # any object that does not respond to dup.
+      def duplicable_value?(value)
+        case value
+        when nil, true, false, Symbol, Numeric, Method then false
+        else value.respond_to?(:dup)
+        end
+      end
+    end
+
+    # The reader method, by default key
+    attr_reader :reader
+
+    # The writer method, by default key=
+    attr_reader :writer
+
+    # An array of metadata for self, used to present the 
+    # delegate in different contexts (ex on the command
+    # line or web).
+    attr_reader :attributes
+
+    # Initializes a new Delegate with the specified key 
+    # and default value.
+    def initialize(reader, writer="#{reader}=", default=nil, attributes={})
+      self.default = default
+      self.reader = reader
+      self.writer = writer
+  
+      @attributes = attributes
+    end
+
+    # Sets the default value for self.
+    def default=(value)
+      @duplicable = Delegate.duplicable_value?(value)
+      @default = value.freeze
+    end
+
+    # Returns the default value, or a duplicate of the default
+    # value if specified and the default value is duplicable
+    # (see Delegate.duplicable_value?)
+    def default(duplicate=true)
+      duplicate && @duplicable ? @default.dup : @default
+    end
+
+    # Sets the reader for self.  The reader is symbolized,
+    # but may also be set to nil.
+    def reader=(value)
+      @reader = value == nil ? value : value.to_sym
+    end
+
+    # Sets the writer for self.  The writer is symbolized,
+    # but may also be set to nil.
+    def writer=(value)
+      @writer = value == nil ? value : value.to_sym
+    end
+
+    # True if another is a kind of Delegate with the same
+    # reader, writer, and default value.  Attributes are
+    # not considered.
+    def ==(another)
+      another.kind_of?(Delegate) &&
+      self.reader == another.reader &&
+      self.writer == another.writer &&
+      self.default(false) == another.default(false)
+    end
+  end
+end

data/lib/configurable/delegate_hash.rb

@@ -0,0 +1,165 @@
+require 'configurable/delegate'
+
+module Configurable
+  
+  # DelegateHash delegates get and set operations to instance methods on a receiver.  
+  #
+  #   class Sample
+  #     attr_accessor :key
+  #   end
+  #   sample = Sample.new
+  #
+  #   dhash = DelegateHash.new
+  #   dhash.delegates[:key] = Delegate.new(:key)
+  #   dhash.bind(sample)
+  #
+  #   sample.key = 'value'
+  #   dhash[:key]                # => 'value'
+  #
+  #   dhash[:key] = 'another'
+  #   sample.key                # => 'another'
+  #
+  # Non-delegate keys are sent to an underlying data store:
+  #
+  #   dhash[:not_delegated] = 'value'
+  #   dhash[:not_delegated]      # => 'value'
+  #
+  #   dhash.store                # => {:not_delegated => 'value'}
+  #   dhash.to_hash              # => {:key => 'another', :not_delegated => 'value'}
+  #
+  class DelegateHash
+
+    # The bound receiver
+    attr_reader :receiver
+
+    # The underlying data store for non-delegate keys
+    attr_reader :store
+
+    # A hash of (key, Delegate) pairs identifying which
+    # keys to delegate to the receiver
+    attr_reader :delegates
+  
+    # Initializes a new DelegateHash.  Note that initialize simply sets the
+    # receiver, it does NOT map stored values the same way bind does.
+    # This allows quick, implicit binding where the bound store is set
+    # up beforehand.
+    #
+    # For more standard binding use: DelegateHash.new.bind(receiver)
+    def initialize(delegates={}, store={}, receiver=nil)
+      @receiver = nil
+      @store = store
+      @delegates = delegates
+      @receiver = receiver
+    end
+
+    # Binds self to the specified receiver.  Mapped keys are
+    # removed from store and sent to their writer method on 
+    # receiver.
+    def bind(receiver)
+      raise ArgumentError, "receiver cannot be nil" if receiver == nil
+      raise ArgumentError, "already bound to: #{@receiver}" if bound? && @receiver != receiver
+        
+      store.keys.each do |key|
+        next unless delegate = delegates[key]
+        receiver.send(delegate.writer, store.delete(key)) if delegate.writer
+      end
+      @receiver = receiver
+  
+      self
+    end
+
+    # Returns true if self is bound to a receiver
+    def bound?
+      receiver != nil
+    end
+
+    # Unbinds self from the specified receiver.  Mapped values
+    # are stored in store.  Returns the unbound receiver.
+    def unbind
+      delegates.each_pair do |key, delegate|
+        store[key] = receiver.send(delegate.reader) if delegate.reader
+      end
+      current_receiver = receiver
+      @receiver = nil
+  
+      current_receiver
+    end
+
+    # Retrieves the value corresponding to the key. If bound? 
+    # and the key is a delegates key, then the value is
+    # obtained from the delegate.reader method on the receiver.
+    def [](key)
+      case 
+      when bound? && delegate = delegates[key]
+        delegate.reader ? receiver.send(delegate.reader) : store[key]
+      else store[key]
+      end
+    end
+
+    # Associates the value the key.  If bound? and the key
+    # is a delegates key, then the value will be forwarded
+    # to the delegate.writer method on the receiver.
+    def []=(key, value)
+      case 
+      when bound? && delegate = delegates[key]
+        delegate.writer ? receiver.send(delegate.writer, value) : store[key] = value
+      else store[key] = value
+      end
+    end
+
+    # True if the key is assigned in self.
+    def has_key?(key)
+      (bound? && delegates.has_key?(key)) || store.has_key?(key) 
+    end
+
+    # Calls block once for each key-value pair stored in self.
+    def each_pair # :yields: key, value
+      delegates.each_pair do |key, delegate|
+        yield(key, receiver.send(delegate.reader)) if delegate.reader
+      end if bound?
+  
+      store.each_pair do |key, value|
+        yield(key, value)
+      end
+    end
+
+    # Updates self to ensure that each delegates key
+    # has a value in self; the delegate.default value is
+    # set if a value does not already exist.
+    #
+    # Returns self.
+    def update
+      delegates.each_pair do |key, delegate|
+        self[key] ||= delegate.default
+      end
+      self
+    end
+
+    # Duplicates self, returning an unbound DelegateHash.
+    def dup
+      duplicate = super()
+      duplicate.instance_variable_set(:@receiver, nil)
+      duplicate.instance_variable_set(:@store, @store.dup)
+      duplicate
+    end
+
+    # Equal if the to_hash values of self and another are equal.
+    def ==(another)
+      another.respond_to?(:to_hash) && to_hash == another.to_hash
+    end
+
+    # Returns self as a hash. 
+    def to_hash
+      hash = store.dup
+      delegates.keys.each do |key|
+        hash[key] = self[key]
+      end if bound?
+      hash
+    end
+
+    # Overrides default inspect to show the to_hash values.
+    def inspect
+      "#<#{self.class}:#{object_id} to_hash=#{to_hash.inspect}>"
+    end
+  end
+end

data/lib/configurable/indifferent_access.rb

@@ -0,0 +1,22 @@
+module Configurable
+  module IndifferentAccess
+
+    def [](key)
+      super(convert(key))
+    end
+  
+    def []=(key, value)
+      super(convert(key), value)
+    end
+  
+    def key?(key)
+      super(convert(key))
+    end
+  
+    private
+  
+    def convert(key)
+      key.kind_of?(String) ? key.to_sym : key
+    end
+  end
+end

data/lib/configurable/validation.rb

@@ -0,0 +1,480 @@
+autoload(:YAML, 'yaml')
+
+module Configurable
+  
+  # Validation generates blocks for common validations and transformations of 
+  # configurations set through Configurable.  In general these blocks load
+  # string inputs as YAML and valdiate the results; non-string inputs are
+  # simply validated.
+  #
+  #   integer = Validation.integer
+  #   integer.class             # => Proc
+  #   integer.call(1)           # => 1
+  #   integer.call('1')         # => 1
+  #   integer.call(nil)         # => ValidationError
+  #
+  #--
+  # Developers: note the unusual syntax for declaring constants that are
+  # blocks defined by lambda... ex:
+  #
+  #   block = lambda {}
+  #   CONST = block
+  #
+  # This syntax plays well with RDoc, which otherwise gets jacked when you
+  # do it all in one step.
+  module Validation
+
+    # Raised when Validation blocks fail.
+    class ValidationError < ArgumentError
+      def initialize(input, validations)
+        super case 
+        when validations.empty?
+          "no validations specified"
+        else
+          "expected #{validations.inspect} but was: #{input.inspect}"
+        end
+      end
+    end
+
+    # Raised when yamlization fails.
+    class YamlizationError < ArgumentError
+      def initialize(input, error)
+        super "#{error} ('#{input}')"
+      end
+    end
+
+    module_function
+
+    # Yaml conversion and checker.  Valid if any of the validations
+    # match in a case statement.  Otherwise raises an error.
+
+    # Returns input if any of the validations match any of the
+    # inputs, as in a case statement.  Raises a ValidationError 
+    # otherwise.  For example:
+    #
+    #   validate(10, [Integer, nil])
+    #
+    # Does the same as:
+    #
+    #   case 10
+    #   when Integer, nil then input
+    #   else raise ValidationError.new(...)
+    #   end
+    #
+    # 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
+  
+        case input
+        when *validations then input
+        else raise ValidationError.new(input, validations)
+        end
+    
+      when nil then input
+      else raise ArgumentError.new("validations must be nil, or an array of valid inputs")
+      end
+    end
+
+    # Attempts to load the input as YAML.  Raises a YamlizationError
+    # for errors.
+    def yamlize(input)
+      begin
+        YAML.load(input)
+      rescue
+        raise YamlizationError.new(input, $!.message)
+      end
+    end
+
+    # Returns a block that calls validate using the block input
+    # and the input validations.  Raises an error if no validations
+    # are specified.
+    def check(*validations)
+      raise ArgumentError.new("no validations specified") if validations.empty?
+      lambda {|input| validate(input, validations) }
+    end
+
+    # Returns a block that loads input strings as YAML, then
+    # calls validate with the result and the input validations.
+    # Non-string inputs are not converted.
+    #
+    #   b = yaml(Integer, nil)
+    #   b.class                 # => Proc
+    #   b.call(1)               # => 1
+    #   b.call("1")             # => 1
+    #   b.call(nil)             # => nil
+    #   b.call("str")           # => ValidationError
+    #
+    # If no validations are specified, the result will be 
+    # returned without validation.
+    def yaml(*validations)
+      lambda do |input|
+        res = input.kind_of?(String) ? yamlize(input) : input
+        validations.empty? ? res : validate(res, validations)
+      end
+    end
+
+    # Returns a block loads a String input as YAML then
+    # validates the result is valid using the input
+    # validations.  If the input is not a String, the
+    # input is validated directly.
+    def yamlize_and_check(*validations)
+      lambda do |input|
+        input = yamlize(input) if input.kind_of?(String)
+        validate(input, validations)
+      end
+    end
+
+    # Returns a block that checks the input is a string.
+    # Moreover, strings are re-evaluated as string 
+    # literals using %Q. 
+    #
+    #   string.class              # => Proc
+    #   string.call('str')        # => 'str'
+    #   string.call('\n')         # => "\n"
+    #   string.call("\n")         # => "\n"
+    #   string.call("%s")         # => "%s"
+    #   string.call(nil)          # => ValidationError
+    #   string.call(:sym)         # => ValidationError
+    #
+    def string(); STRING; end
+    string_validation_block = lambda do |input|
+      input = validate(input, [String])
+      eval %Q{"#{input}"}
+    end
+    STRING = string_validation_block
+
+    # 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
+    # to be consistent with the other [class]_or_nil
+    # methods.
+    #
+    #   string_or_nil.call('~')   # => nil
+    #   string_or_nil.call(nil)   # => nil
+    def string_or_nil(); STRING_OR_NIL; end
+    string_or_nil_validation_block = lambda do |input|
+      input = validate(input, [String, nil])
+      case input
+      when nil, '~' then nil 
+      else eval %Q{"#{input}"}
+      end
+    end
+    STRING_OR_NIL = string_or_nil_validation_block
+
+    # Returns a block that checks the input is a symbol.
+    # String inputs are loaded as yaml first.
+    #
+    #   symbol.class              # => Proc
+    #   symbol.call(:sym)         # => :sym
+    #   symbol.call(':sym')       # => :sym
+    #   symbol.call(nil)          # => ValidationError
+    #   symbol.call('str')        # => ValidationError
+    #
+    def symbol(); SYMBOL; end
+    SYMBOL = yamlize_and_check(Symbol)
+
+    # 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 = yamlize_and_check(Symbol, nil)
+
+    # Returns a block that checks the input is true, false or nil.
+    # String inputs are loaded as yaml first.
+    #
+    #   boolean.class             # => Proc
+    #   boolean.call(true)        # => true
+    #   boolean.call(false)       # => false
+    #   boolean.call(nil)         # => nil
+    #
+    #   boolean.call('true')      # => true
+    #   boolean.call('yes')       # => true
+    #   boolean.call('FALSE')     # => false
+    #
+    #   boolean.call(1)           # => ValidationError
+    #   boolean.call("str")       # => ValidationError
+    #
+    def boolean(); BOOLEAN; end
+    BOOLEAN = yamlize_and_check(true, false, nil)
+
+    # Same as boolean.
+    def switch(); SWITCH; end
+    SWITCH = yamlize_and_check(true, false, nil)
+
+    # Same as boolean.
+    def flag(); FLAG; end
+    FLAG = yamlize_and_check(true, false, nil)
+
+    # Returns a block that checks the input is an array.
+    # String inputs are loaded as yaml first.
+    #
+    #   array.class               # => Proc
+    #   array.call([1,2,3])       # => [1,2,3]
+    #   array.call('[1, 2, 3]')   # => [1,2,3]
+    #   array.call(nil)           # => ValidationError
+    #   array.call('str')         # => ValidationError
+    #
+    def array(); ARRAY; end
+    ARRAY = yamlize_and_check(Array)
+
+    # Same as array but allows nil:
+    #
+    #   array_or_nil.call('~')    # => nil
+    #   array_or_nil.call(nil)    # => nil
+    def array_or_nil(); ARRAY_OR_NIL; end
+    ARRAY_OR_NIL = yamlize_and_check(Array, nil)
+
+    # Returns a block that checks the input is an array,
+    # then yamlizes each string value of the array.
+    #
+    #   list.class                # => Proc
+    #   list.call([1,2,3])        # => [1,2,3]
+    #   list.call(['1', 'str'])   # => [1,'str']
+    #   list.call('str')          # => ValidationError
+    #   list.call(nil)            # => ValidationError
+    #
+    def list(); LIST; end
+    list_block = lambda do |input|
+      validate(input, [Array]).collect do |arg| 
+        arg.kind_of?(String) ? yamlize(arg) : arg
+      end
+    end
+    LIST = list_block
+
+    # Returns a block that checks the input is a hash.
+    # String inputs are loaded as yaml first.
+    #
+    #   hash.class                     # => Proc
+    #   hash.call({'key' => 'value'})  # => {'key' => 'value'}
+    #   hash.call('key: value')        # => {'key' => 'value'}
+    #   hash.call(nil)                 # => ValidationError
+    #   hash.call('str')               # => ValidationError
+    #
+    def hash(); HASH; end
+    HASH = yamlize_and_check(Hash)
+
+    # Same as hash but allows nil:
+    #
+    #   hash_or_nil.call('~')          # => nil
+    #   hash_or_nil.call(nil)          # => nil
+    def hash_or_nil(); HASH_OR_NIL; end
+    HASH_OR_NIL = yamlize_and_check(Hash, nil)
+
+    # Returns a block that checks the input is an integer.
+    # String inputs are loaded as yaml first.
+    #
+    #   integer.class             # => Proc
+    #   integer.call(1)           # => 1
+    #   integer.call('1')         # => 1
+    #   integer.call(1.1)         # => ValidationError
+    #   integer.call(nil)         # => ValidationError
+    #   integer.call('str')       # => ValidationError
+    #
+    def integer(); INTEGER; end
+    INTEGER = yamlize_and_check(Integer)
+
+    # 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 = yamlize_and_check(Integer, nil)
+
+    # Returns a block that checks the input is a float.
+    # String inputs are loaded as yaml first.
+    #
+    #   float.class               # => Proc
+    #   float.call(1.1)           # => 1.1
+    #   float.call('1.1')         # => 1.1
+    #   float.call('1.0e+6')      # => 1e6
+    #   float.call(1)             # => ValidationError
+    #   float.call(nil)           # => ValidationError
+    #   float.call('str')         # => ValidationError
+    #
+    def float(); FLOAT; end
+    FLOAT = yamlize_and_check(Float)
+
+    # 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 = yamlize_and_check(Float, nil)
+
+    # 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
+    #
+    def num(); NUMERIC; end
+    NUMERIC = yamlize_and_check(Numeric)
+
+    # 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 = yamlize_and_check(Numeric, nil)
+
+    # Returns a block that checks the input is a regexp.
+    # String inputs are converted to regexps using
+    # Regexp#new.
+    #
+    #   regexp.class              # => Proc
+    #   regexp.call(/regexp/)     # => /regexp/
+    #   regexp.call('regexp')     # => /regexp/
+    #
+    #   # use of ruby-specific flags can turn on/off 
+    #   # features like case insensitive matching
+    #   regexp.call('(?i)regexp') # => /(?i)regexp/
+    #
+    def regexp(); REGEXP; end
+    regexp_block = lambda do |input|
+      input = Regexp.new(input) if input.kind_of?(String)
+      validate(input, [Regexp])
+    end
+    REGEXP = regexp_block
+
+    # Same as regexp but allows nil. Note the special
+    # behavior of the nil string '~' -- rather than
+    # being converted to a regexp, it is processed as 
+    # nil to be consistent with the other [class]_or_nil
+    # methods.
+    #
+    #   regexp_or_nil.call('~')   # => nil
+    #   regexp_or_nil.call(nil)   # => nil
+    def regexp_or_nil(); REGEXP_OR_NIL; end
+    regexp_or_nil_block = lambda do |input|
+      input = case input
+      when nil, '~' then nil
+      when String then Regexp.new(input)
+      else input
+      end
+  
+      validate(input, [Regexp, nil])
+    end
+    REGEXP_OR_NIL = regexp_or_nil_block
+
+    # Returns a block that checks the input is a range.
+    # String inputs are split into a beginning and
+    # end if possible, where each part is loaded as
+    # yaml before being used to construct a Range.a
+    #
+    #   range.class               # => Proc
+    #   range.call(1..10)         # => 1..10
+    #   range.call('1..10')       # => 1..10
+    #   range.call('a..z')        # => 'a'..'z'
+    #   range.call('-10...10')    # => -10...10
+    #   range.call(nil)           # => ValidationError
+    #   range.call('1.10')        # => ValidationError
+    #   range.call('a....z')      # => ValidationError
+    #
+    def range(); RANGE; end
+    range_block = lambda do |input|
+      if input.kind_of?(String) && input =~ /^([^.]+)(\.{2,3})([^.]+)$/
+        input = Range.new(yamlize($1), yamlize($3), $2.length == 3) 
+      end
+      validate(input, [Range])
+    end
+    RANGE = range_block
+
+    # Same as range but allows nil:
+    #
+    #   range_or_nil.call('~')    # => nil
+    #   range_or_nil.call(nil)    # => nil
+    def range_or_nil(); RANGE_OR_NIL; end
+    range_or_nil_block = lambda do |input|
+      input = case input
+      when nil, '~' then nil
+      when String
+        if input =~ /^([^.]+)(\.{2,3})([^.]+)$/
+          Range.new(yamlize($1), yamlize($3), $2.length == 3)
+        else
+          input
+        end
+      else input
+      end
+  
+      validate(input, [Range, nil])
+    end
+    RANGE_OR_NIL = range_or_nil_block
+
+    # Returns a block that checks the input is a Time. String inputs are 
+    # loaded using Time.parse and then converted into times.  Parsed times 
+    # are local unless specified otherwise.
+    #
+    #   time.class               # => Proc
+    #
+    #   now = Time.now
+    #   time.call(now)           # => now
+    #
+    #   time.call('2008-08-08 20:00:00.00 +08:00').getutc.strftime('%Y/%m/%d %H:%M:%S')
+    #   #  => '2008/08/08 12:00:00'
+    #
+    #   time.call('2008-08-08').strftime('%Y/%m/%d %H:%M:%S')
+    #   #  => '2008/08/08 00:00:00'
+    #
+    #   time.call(1)             # => ValidationError
+    #   time.call(nil)           # => ValidationError
+    #
+    # Warning: Time.parse will parse a valid time (Time.now)
+    # even when no time is specified:
+    #
+    #   time.call('str').strftime('%Y/%m/%d %H:%M:%S')      
+    #   # => Time.now.strftime('%Y/%m/%d %H:%M:%S')      
+    #
+    def time()
+      # adding this here is a compromise to lazy-load the parse
+      # method (autoload doesn't work since Time already exists)
+      require 'time' unless Time.respond_to?(:parse)
+      TIME
+    end
+
+    time_block = lambda do |input|
+      input = Time.parse(input) if input.kind_of?(String)
+      validate(input, [Time])
+    end
+    TIME = time_block
+
+    # Same as time but allows nil:
+    #
+    #   time_or_nil.call('~')    # => nil
+    #   time_or_nil.call(nil)    # => nil
+    def time_or_nil()
+      # adding this check is a compromise to autoload the parse 
+      # method (autoload doesn't work since Time already exists)
+      require 'time' unless Time.respond_to?(:parse)
+      TIME_OR_NIL
+    end
+
+    time_or_nil_block = lambda do |input|
+      input = case input
+      when nil, '~' then nil
+      when String then Time.parse(input)
+      else input
+      end
+  
+      validate(input, [Time, nil])
+    end 
+    TIME_OR_NIL = time_or_nil_block
+
+    # A hash of default attributes for the validation blocks.
+    ATTRIBUTES = Hash.new({})
+    ATTRIBUTES[SWITCH] = {:type => :switch}
+    ATTRIBUTES[FLAG]   = {:type => :flag}
+    ATTRIBUTES[LIST]   = {:type => :list, :split => ','}
+    ATTRIBUTES[ARRAY]  = {:arg_name => "'[a, b, c]'"}
+    ATTRIBUTES[HASH]   = {:arg_name => "'{one: 1, two: 2}'"}
+  end
+end