configurable 0.5.0 → 0.6.0

data/lib/configurable/config.rb

@@ -0,0 +1,97 @@
+module Configurable
+  
+  # Configs are used by ConfigHash to determine how to delegate read/write
+  # operations to a receiver.  Configs also track metadata related to their
+  # presentation in various contexts.
+  class Config
+    class << self
+      
+      # Determines if the value is duplicable.  Non-duplicable values 
+      # include nil, true, false, Symbol, Numeric, Method, Module, and 
+      # any object that does not respond to dup.
+      def duplicable_value?(value)
+        case value
+        when nil, true, false, Symbol, Numeric, Method, Module then false
+        else value.respond_to?(:dup)
+        end
+      end
+    end
+      
+    # The reader method called on a receiver during get
+    attr_reader :reader
+
+    # The writer method called on a receiver during set
+    attr_reader :writer
+    
+    # An hash of metadata for self, often used to indicate how a config is
+    # presented in different contexts (ex on the command line, in a web form,
+    # or a desktop app).
+    attr_reader :attributes
+
+    # Initializes a new Config.
+    def initialize(reader, writer="#{reader}=", default=nil, attributes={}, init=true, dup=nil)
+      self.reader = reader
+      self.writer = writer
+      @default = default
+      @attributes = attributes
+      @init = init
+      @dup = dup.nil? ? Config.duplicable_value?(default) : dup
+    end
+    
+    # Returns the default value.  If duplicate is specified and the default
+    # may be duplicated (see Config.duplicable_value?) then a duplicate
+    # of the default is returned.
+    def default(duplicate=true)
+      duplicate && @dup ? @default.dup : @default
+    end
+    
+    # Returns the value for the specified attribute, or default if the
+    # attribute is unspecified.
+    def [](key, default=nil)
+      attributes.has_key?(key) ? attributes[key] : default
+    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
+    
+    # Sets the default value on the receiver.  Normally this method is only
+    # called during Configurable#initialize_config, and only then when init?
+    # returns true.
+    def init(receiver)
+      receiver.send(writer, default)
+    end
+    
+    # Returns true or false as specified in new.  True indicates that this
+    # delegate is allowed to initialize values on the receiver during
+    # Configurable#initialize_config.
+    def init?
+      @init
+    end
+    
+    # Returns an inspection string.
+    def inspect
+      "#<#{self.class}:#{object_id} reader=#{reader} writer=#{writer} default=#{default.inspect} >"
+    end
+    
+    protected
+    
+    # Sets the reader for self, assuring the reader is not nil.
+    def reader=(value) # :nodoc:
+      raise ArgumentError, "reader may not be nil" if value.nil?
+      @reader = value.to_sym
+    end
+
+    # Sets the writer for self, assuring the writer is not nil.
+    def writer=(value) # :nodoc:
+      raise ArgumentError, "writer may not be nil" if value.nil?
+      @writer = value.to_sym
+    end
+  end
+end

data/lib/configurable/config_hash.rb

@@ -0,0 +1,198 @@
+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
+  #
+  class ConfigHash
+
+    # The bound receiver
+    attr_reader :receiver
+
+    # 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
+      @store = store
+      
+      import(store) if import_store
+    end
+    
+    # Returns receiver.class.configurations.
+    def configs
+      receiver.class.configurations
+    end
+    
+    # Imports stored values that can be mapped to the receiver.  The values
+    # are removed from store in the process.  Returns self.
+    #
+    # 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))
+      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] }
+    end
+    
+    # Retrieves the value for the key, either from the receiver or the store.
+    def [](key)
+      if config = configs[key]
+        config.get(receiver)
+      else
+        store[key]
+      end
+    end
+
+    # Stores a value for the key, either on the receiver or in the store.
+    def []=(key, value)
+      if config = configs[key]
+        config.set(receiver, value)
+      else
+        store[key] = value
+      end
+    end
+    
+    # Returns the union of configs and store keys.
+    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) 
+    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]
+        if config = configs[key]
+          config.set(receiver, value)
+        else
+          store[key] = value
+        end
+      end
+    end
+    
+    # Calls block once for each key-value pair stored in self.
+    def each_pair # :yields: key, value
+      configs.each_pair do |key, config|
+        yield(key, config.get(receiver))
+      end
+      
+      store.each_pair do |key, value|
+        yield(key, value)
+      end
+    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.  Any ConfigHash values are recursively
+    # hashified, to account for nesting.
+    def to_hash(scrub=false, &block)
+      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
+        end
+        
+        if block_given?
+          yield(hash, key, value)
+        else
+          hash[key] = value
+        end
+      end
+      hash
+    end
+
+    # Returns an inspection string.
+    def inspect
+      "#<#{self.class}:#{object_id} to_hash=#{to_hash.inspect}>"
+    end
+  end
+end

data/lib/configurable/indifferent_access.rb

@@ -7,7 +7,7 @@ module Configurable
   # Note that the indifference produced by this module is very thin indeed.
   # Strings may still be used as keys through store/fetch, and
   # existing string keys are not changed in any way.  Nonetheless,
-  # these methods are sufficient for Configurable and DelegateHash.
+  # these methods are sufficient for Configurable and ConfigHash.
   module IndifferentAccess
     
     # Symbolizes string keys and calls super.

data/lib/configurable/module_methods.rb

@@ -1,27 +1,17 @@
+require 'lazydoc'
 require 'configurable/class_methods'
 
 module Configurable
   module ModuleMethods
+    module_function
     
     # 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
+    def included(base)
+      base.extend ClassMethods
+      base.extend Lazydoc::Attributes
+      base.extend ModuleMethods unless base.kind_of?(Class)
       
+      ClassMethods.initialize(base)
       super
     end
   end

data/lib/configurable/nest_config.rb

@@ -0,0 +1,78 @@
+require 'configurable/config'
+
+module Configurable
+  
+  # NestConfigs are used to nest configurable classes.
+  class NestConfig < Config
+    
+    # The nested configurable class
+    attr_reader :nest_class
+    
+    # Initializes a new NestConfig
+    def initialize(nest_class, reader, writer="#{reader}=", attributes={}, init=true)
+      self.nest_class = nest_class
+      self.reader = reader
+      self.writer = writer
+      @attributes = attributes
+      @init = init
+    end
+    
+    # Returns a hash of the default configuration values for nest_class.
+    def default
+      default = {}
+      nest_class.configurations.each_pair do |key, delegate|
+        default[key] = delegate.default
+      end
+      default
+    end
+    
+    # Calls the reader on the reciever to retreive an instance of the 
+    # nest_class and returns it's config.  Returns nil if the reader
+    # returns nil.
+    def get(receiver)
+      if instance = receiver.send(reader)
+        instance.config
+      else
+        nil
+      end
+    end
+    
+    # Calls the reader on the reciever to retrieve an instance of the
+    # nest_class, and reconfigures it with value.  The instance will
+    # be initialized by init if necessary.
+    #
+    # If value is an instance of the nest_class, then it will be set
+    # by calling writer.
+    def set(receiver, value)
+      if value.kind_of?(nest_class)
+        receiver.send(writer, value)
+      else
+        configurable = receiver.send(reader) || init(receiver)
+        configurable.reconfigure(value)
+      end
+    end
+    
+    # Initializes an instance of nest_class and sets it on the receiver.  The
+    # instance is initialized by calling nest_class.new with no arguments.
+    def init(receiver)
+      receiver.send(writer, nest_class.new)
+    end
+    
+    # Returns an inspection string.
+    def inspect
+      "#<#{self.class}:#{object_id} reader=#{reader} writer=#{writer} nest_class=#{nest_class.inspect} >"
+    end
+    
+    protected
+    
+    # sets nest_class, checking that the nested class
+    # is both a Class and Configurable
+    def nest_class=(nest_class) # :nodoc:
+      unless nest_class.kind_of?(Class) && nest_class.ancestors.include?(Configurable)
+        raise ArgumentError, "not a Configurable class: #{nest_class}"
+      end
+      
+      @nest_class = nest_class
+    end
+  end
+end

data/lib/configurable/ordered_hash_patch.rb

@@ -0,0 +1,85 @@
+module Configurable
+  
+  # Beginning with ruby 1.9, Hash tracks the order of insertion and methods
+  # like each_pair return pairs in order.  Configurable leverages this feature
+  # to keep configurations in order for the command line documentation produced
+  # by ConfigParser.
+  #
+  # Pre-1.9 ruby implementations require a patched Hash that tracks insertion
+  # order.  This very thin subclass of hash does that for ASET insertions and
+  # each_pair.  OrderedHashPatches are used as the configurations object in 
+  # Configurable classes for pre-1.9 ruby implementations and for nothing else.
+  #
+  # OrderedHashPatch is only loaded for pre-1.9 ruby implementations.
+  class OrderedHashPatch < Hash
+    def initialize
+      super
+      @insertion_order = []
+    end
+    
+    # ASET insertion, tracking insertion order.
+    def []=(key, value)
+      @insertion_order << key unless @insertion_order.include?(key)
+      super
+    end
+    
+    # Keys, sorted into insertion order
+    def keys
+      super.sort_by do |key|
+        @insertion_order.index(key) || length
+      end
+    end
+    
+    # Yields each key-value pair to the block in insertion order.
+    def each_pair
+      keys.each do |key|
+        yield(key, fetch(key))
+      end
+    end
+    
+    # Merges another into self in a way that preserves insertion order.
+    def merge!(another)
+      another.each_pair do |key, value|
+        self[key] = value
+      end
+    end
+    
+    # Ensures the insertion order of duplicates is separate from parents.
+    def initialize_copy(orig)
+      super
+      @insertion_order = orig.instance_variable_get(:@insertion_order).dup
+    end
+    
+    # Overridden to load an array of [key, value] pairs in order (see to_yaml).
+    # The default behavior for loading from a hash of key-value pairs is
+    # preserved, but the insertion order will not be preserved.
+    def yaml_initialize( tag, val )
+      @insertion_order ||= []
+     
+      if Array === val
+        val.each do |k, v|
+          self[k] = v
+        end
+      else
+        super
+      end
+    end
+    
+    # Overridden to preserve insertion order by serializing self as an array
+    # of [key, value] pairs.
+    def to_yaml( opts = {} )
+      YAML::quick_emit( object_id, opts ) do |out|
+        out.seq( taguri, to_yaml_style ) do |seq|
+          each_pair do |key, value|
+            seq.add( [key, value] )
+          end
+        end
+      end
+    end
+  end
+  
+  module ClassMethods
+    remove_const(:CONFIGURATIONS_CLASS)
+    CONFIGURATIONS_CLASS = OrderedHashPatch
+  end
+end