configurable 0.7.0 → 1.0.0

data/lib/configurable/config_classes.rb

@@ -0,0 +1,3 @@
+require 'configurable/config_classes/scalar_config'
+require 'configurable/config_classes/list_config'
+require 'configurable/config_classes/nest_config'

data/lib/configurable/config_classes/list_config.rb

@@ -0,0 +1,26 @@
+module Configurable
+  module ConfigClasses
+    class ListConfig < ScalarConfig
+      
+      def initialize(key, attrs={})
+        unless attrs.has_key?(:default)
+          attrs[:default] = []
+        end
+        
+        super
+      end
+      
+      def cast(values)
+        results = []
+        values.each {|value| results << super(value) } 
+        results
+      end
+      
+      def uncast(values)
+        results = []
+        values.each {|value| results << super(value) } 
+        results
+      end
+    end
+  end
+end

data/lib/configurable/config_classes/nest_config.rb

@@ -0,0 +1,50 @@
+module Configurable
+  module ConfigClasses
+    
+    # Represents a config where the input is expected to be Configurable.
+    class NestConfig < ScalarConfig
+      
+      def initialize(key, attrs={})
+        unless attrs.has_key?(:default)
+          attrs[:default] = {}
+        end
+        
+        unless attrs.has_key?(:type)
+          attrs[:type] = NestType.new(attrs)
+        end
+        
+        super
+        
+        unless type.respond_to?(:init)
+          raise "invalid type for #{self}: #{type.inspect}"
+        end
+      end
+      
+      # Calls the reader on the reciever to retreive an instance of the
+      # configurable_class and returns it's config.  Returns nil if the reader
+      # returns nil.
+      def get(receiver)
+        if configurable = receiver.send(reader)
+          configurable.config
+        else
+          nil
+        end
+      end
+  
+      # Calls the reader on the reciever to retrieve an instance of the
+      # configurable_class, and reconfigures it with value.  The instance will
+      # be initialized by init if necessary.
+      #
+      # If value is an instance of the configurable_class, then it will be set
+      # by calling writer.
+      def set(receiver, value)
+        unless value.respond_to?(:config)
+          value = default.merge(value)
+          value = type.init(value)
+        end
+        
+        receiver.send(writer, value)
+      end
+    end
+  end
+end

data/lib/configurable/config_classes/scalar_config.rb

@@ -0,0 +1,91 @@
+require 'configurable/config_types'
+
+module Configurable
+  module ConfigClasses
+    # ConfigClasses are used by ConfigHash to delegate get/set configs on a
+    # receiver and to map configs between user interfaces.
+    class ScalarConfig
+      include ConfigTypes
+      
+      # The config key, used as a hash key for access.
+      attr_reader :key
+    
+      # The config name used in interfaces where only word-based names are
+      # appropriate. Names are strings consisting of only word characters.
+      attr_reader :name
+    
+      # The reader method called on a receiver during get.
+      attr_reader :reader
+    
+      # The writer method called on a receiver during set.
+      attr_reader :writer
+    
+      # The default config value.
+      attr_reader :default
+      
+      # The config type for self (defaults to an ObjectType)
+      attr_reader :type
+      
+      # A hash of information used to render self in various contexts.
+      attr_reader :metadata
+      
+      # Initializes a new Config.  Specify attributes like default, reader,
+      # writer, type, etc. within attrs.
+      def initialize(key, attrs={})
+        @key      = key
+        @name     = attrs[:name] || @key.to_s
+        check_name(@name)
+        
+        @default  = attrs[:default]
+        @type     = attrs[:type] || ObjectType.new
+        check_default(@default)
+        
+        @reader   = (attrs[:reader] || name).to_sym
+        @writer   = (attrs[:writer] || "#{name}=").to_sym
+        @metadata = attrs[:metadata] || {}
+      end
+    
+      def [](key)
+        metadata[key]
+      end
+      
+      # Calls reader on the receiver and returns the result.
+      def get(receiver)
+        receiver.send(reader)
+      end
+    
+      # Calls writer on the receiver with the value.
+      def set(receiver, value)
+        receiver.send(writer, value)
+      end
+      
+      def cast(input)
+        type.cast(input)
+      end
+      
+      def uncast(value)
+        type.uncast(value)
+      end
+      
+      # Returns an inspect string.
+      def inspect
+        "#<#{self.class}:#{object_id} key=#{key} name=#{name} default=#{default.inspect} reader=#{reader} writer=#{writer} >"
+      end
+    
+      protected
+    
+      def check_name(name) # :nodoc
+        unless name.kind_of?(String)
+          raise "invalid name: #{name.inspect} (not a String)"
+        end
+
+        unless name =~ /\A\w+\z/
+          raise NameError.new("invalid name: #{name.inspect} (includes non-word characters)")
+        end
+      end
+      
+      def check_default(default) # :nodoc:
+      end
+    end
+  end
+end

data/lib/configurable/config_hash.rb

@@ -1,110 +1,72 @@
-require 'configurable/nest_config'
-
 module Configurable
   
   # ConfigHash acts like a hash that maps get and set operations as specified
-  # in a Configurable's class configurations.
-  #
-  #   class Sample
-  #     include Configurable
-  #     config :key
-  #   end
-  #
-  #   sample = Sample.new
-  #   sample.config.class               # => ConfigHash
-  #
-  #   sample.key = 'value'
-  #   sample.config[:key]               # => 'value'
-  #
-  #   sample.config[:key] = 'another'
-  #   sample.key                        # => 'another'
-  #
-  # Non-configuration keys are sent to an underlying data store:
-  #
-  #   sample.config[:not_delegated] = 'value'
-  #   sample.config[:not_delegated]     # => 'value'
-  #
-  #   sample.config.store               # => {:not_delegated => 'value'}
-  #   sample.config.to_hash             # => {:key => 'another', :not_delegated => 'value'}
-  #
-  # ==== IndifferentAccess
-  #
-  # A ConfigHash uses the receiver class configurations to determine when and
-  # how to map get/set operations. In cases where multiple keys need to map
-  # in the same way (for example when you want indifferent access for strings
-  # and symbols), simply extend the class configurations so that the AGET ([])
-  # method returns the correct Config in all cases.
-  #
-  # ==== Inconsistency
-  #
-  # ConfigHashes can fall into an inconsistent state if you manually add values
-  # to store that would normally be mapped to the receiver.  This is both easy
-  # to avoid and easy to repair.
-  #
-  # To avoid inconsistency, don't manually add values to the store and set
-  # import_store to true during initialization.  To repair inconsistency,
-  # import the current store to self.
-  #
-  #   config_hash = Sample.new.config
-  #   config_hash[:key] = 'a'
-  #   config_hash.store[:key] = 'b'
-  #
-  #   config_hash[:key]          # => 'a'
-  #   config_hash.to_hash        # => {:key => 'b'}
-  #   config_hash.inconsistent?  # => true
-  #
-  #   config_hash.import(config_hash.store)
-  #
-  #   config_hash[:key]          # => 'b'
-  #   config_hash.to_hash        # => {:key => 'b'}
-  #   config_hash.inconsistent?  # => false
-  #
+  # in by a receiver's class configurations. Non-configuration keys are sent
+  # to an underlying data store.
   class ConfigHash
-
+    # A frozen empty hash returned by configs for unbound config hashes.
+    EMPTY_HASH =  {}.freeze
+    
     # The bound receiver
     attr_reader :receiver
-
-    # The underlying data store; setting values in store directly
-    # can result in an inconsistent state.  Use []= instead.
+    
+    # The underlying data store; setting values in store directly can result
+    # in an inconsistent state.  Use []= instead.
     attr_reader :store
-  
-    # Initializes a new ConfigHash.  Initialize normally imports values from
-    # store to ensure it doesn't contain entries that could be stored on the
-    # receiver.  
-    # 
-    # Setting import_store to false allows quick initialization but can result
-    # in an inconsistent state.
-    def initialize(receiver, store={}, import_store=true)
-      @receiver = receiver
+   
+    # Initializes a new ConfigHash.
+    def initialize(store={}, receiver=nil)
       @store = store
-      
-      import(store) if import_store
-    end
-    
-    # Returns receiver.class.configurations.
-    def configs
-      receiver.class.configurations
+      @receiver = receiver
     end
     
-    # Imports stored values that can be mapped to the receiver.  The values
-    # are removed from store in the process.  Returns self.
+    # Binds the configs in store to the receiver by setting each on the
+    # receiver (via config.set).  Bound configs are removed from store.
     #
-    # Primarily used to create a consistent state for self (see above).
-    def import(store)
-      configs = self.configs # cache as an optimization
-      store.keys.each do |key|
-        next unless config = configs[key]
-        config.set(receiver, store.delete(key))
+    # Unbinds self from the current receiver, if needed.
+    def bind(receiver)
+      unbind if bound?
+      
+      @receiver = receiver
+      configs.each_pair do |key, config|
+        value = store.has_key?(key) ? store.delete(key) : config.default
+        config.set(receiver, value)
       end
       
       self
     end
     
-    # Returns true if the store has entries that can be stored on the
-    # receiver.
-    def inconsistent?
-      configs = self.configs # cache as an optimization
-      store.keys.any? {|key| configs[key] }
+    # Unbinds the configs set on receiver by getting each value (via
+    # config.get) and setting the result into store. Does nothing if no
+    # receiver is set.
+    def unbind
+      if bound?
+        configs.each_pair do |key, config|
+          store[key] = config.get(receiver)
+        end
+        @receiver = nil
+      end
+      self
+    end
+    
+    # Returns true if bound to a receiver.
+    def bound?
+      @receiver ? true : false
+    end
+    
+    # Returns the class configs for the bound receiver, or an empty hash if
+    # unbound (specifically EMPTY_HASH).
+    def configs
+      # Caching here is not necessary or preferred as configurations are
+      # cached on the class (which allows late inclusion of configurable
+      # modules to work properly).
+      bound? ? receiver.class.configs : EMPTY_HASH
+    end
+    
+    # Returns true if bound to a receiver and no configs values are set in
+    # store (ie all config values are stored on the receiver).
+    def consistent?
+      bound? && (store.keys & configs.keys).empty?
     end
     
     # Retrieves the value for the key, either from the receiver or the store.
@@ -129,26 +91,23 @@ module Configurable
     def keys
       configs.keys | store.keys
     end
-
+    
     # True if the key is a key in configs or store.
     def has_key?(key)
-      configs[key] != nil || store.has_key?(key) 
+      configs.has_key?(key) || store.has_key?(key) 
     end
     
     # Merges another with self.
     def merge!(another)
-      # cache configs and inline set as a significant optimization
       configs = self.configs
-      (configs.keys | another.keys).each do |key|
-        next unless another.has_key?(key)
-        
-        value = another[key]
+      another.each_pair do |key, value|
         if config = configs[key]
           config.set(receiver, value)
         else
           store[key] = value
         end
       end
+      self
     end
     
     # Calls block once for each key-value pair stored in self.
@@ -166,30 +125,46 @@ module Configurable
     def ==(another)
       another.respond_to?(:to_hash) && to_hash == another.to_hash
     end
-
+    
     # Returns self as a hash.  Any ConfigHash values are recursively
     # hashified, to account for nesting.
-    def to_hash(scrub=false, &block)
+    def to_hash
       hash = {}
       each_pair do |key, value|
         if value.kind_of?(ConfigHash)
-          value = value.to_hash(scrub, &block)
-        end
-        
-        if scrub
-          config = configs[key]
-          next if config && config.default == value
+          value = value.to_hash
         end
         
-        if block_given?
-          yield(hash, key, value)
-        else
-          hash[key] = value
-        end
+        hash[key] = value
       end
       hash
     end
-
+    
+    # Returns self exported as a hash of raw configs (ie name keys and uncast
+    # values).
+    def export
+      configs.export(to_hash)
+    end
+    
+    # Imports a hash of raw configs (ie name keys and uncast values) and
+    # merges the result with self.
+    def import(another)
+      merge! configs.import(another)
+    end
+    
+    def parse(argv=ARGV, options={}, &block)
+      parse!(argv.dup, options, &block)
+    end
+    
+    def parse!(argv=ARGV, options={}, &block)
+      parser(options, &block).parse!(argv)
+    end
+    
+    def parser(options={}, &block)
+      options = {:assign_defaults => false}.merge(options)
+      configs.to_parser(self, options, &block)
+    end
+    
     # Returns an inspection string.
     def inspect
       "#<#{self.class}:#{object_id} to_hash=#{to_hash.inspect}>"

data/lib/configurable/config_types.rb

@@ -0,0 +1,6 @@
+require 'configurable/config_types/object_type'
+require 'configurable/config_types/string_type'
+require 'configurable/config_types/boolean_type'
+require 'configurable/config_types/integer_type'
+require 'configurable/config_types/float_type'
+require 'configurable/config_types/nest_type'

data/lib/configurable/config_types/boolean_type.rb

@@ -0,0 +1,22 @@
+module Configurable
+  module ConfigTypes
+    class BooleanType < ObjectType
+      matches TrueClass, FalseClass
+      
+      # Casts the input to a boolean ie:
+      #
+      #   true, 'true'   => true
+      #   false, 'false  => false
+      #
+      # All other inputs raise an ArgumentError.
+      def cast(input)
+        case input
+        when true, false then input
+        when 'true'      then true
+        when 'false'     then false
+        else raise ArgumentError, "invalid value for boolean: #{input.inspect}"
+        end
+      end
+    end
+  end
+end