configurable 0.1.0 → 0.3.0

data/lib/configurable/delegate_hash.rb

@@ -27,12 +27,19 @@ module Configurable
   #   dhash.store                # => {:not_delegated => 'value'}
   #   dhash.to_hash              # => {:key => 'another', :not_delegated => 'value'}
   #
+  # ==== IndifferentAccess
+  #
+  # The delegates hash maps keys to Delegate objects.  In cases where multiple
+  # keys need to map to the same delegate (for example when you want indifferent
+  # access for strings and symbols), simply extend the delegate hash so that the
+  # AGET ([]) method returns the correct delegate in all cases.
+  #
   class DelegateHash
 
     # The bound receiver
     attr_reader :receiver
 
-    # The underlying data store for non-delegate keys
+    # The underlying data store
     attr_reader :store
 
     # A hash of (key, Delegate) pairs identifying which
@@ -40,31 +47,32 @@ module Configurable
     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.
+    # receiver, it does NOT map stored values the same way bind does.  This
+    # allows quick, implicit binding when the 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.
+    # Binds self to the specified receiver.  Delegate values are removed from
+    # store and sent to their writer method on receiver.  If the store has no
+    # value for a delegate key, the delegate default value will be used.
     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
+      
+      if bound?
+        if @receiver == receiver
+          return(self)
+        else
+          raise ArgumentError, "already bound to: #{@receiver}"
+        end
       end
+      
       @receiver = receiver
-  
+      map(store)
       self
     end
 
@@ -73,74 +81,70 @@ module Configurable
       receiver != nil
     end
 
-    # Unbinds self from the specified receiver.  Mapped values
+    # Unbinds self from the specified receiver.  Delegate 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
+      unmap(store)
       @receiver = nil
-  
-      current_receiver
+      self
     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.
+    # Retrieves the value corresponding to the key.  When bound, delegates with
+    # readers pull values from the receiver; otherwise the value in store will
+    # be returned.  When unbound, if the store has no value for a delegate, the
+    # delgate default value will be returned.
     def [](key)
-      case 
-      when bound? && delegate = delegates[key]
-        delegate.reader ? receiver.send(delegate.reader) : store[key]
-      else store[key]
+      return store[key] unless delegate = delegates[key]
+      
+      case
+      when bound? && delegate.reader
+        receiver.send(delegate.reader)
+      when store.has_key?(key)
+        store[key]
+      else
+        store[key] = delegate.default
       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.
+    # Stores a value for the key.  When bound, delegates with writers send the
+    # value to the receiver; otherwise values are stored in store.
     def []=(key, value)
-      case 
-      when bound? && delegate = delegates[key]
-        delegate.writer ? receiver.send(delegate.writer, value) : store[key] = value
-      else store[key] = value
+      if bound? && delegate = delegates[key]
+        if delegate.writer
+          receiver.send(delegate.writer, value)
+          return
+        end
       end
+      
+      store[key] = value
     end
-
-    # True if the key is assigned in self.
-    def has_key?(key)
-      (bound? && delegates.has_key?(key)) || store.has_key?(key) 
+    
+    # Returns the union of delegate and store keys.
+    def keys
+      delegates.keys | store.keys
     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
+    # True if the key is an assigned delegate or store key.
+    def has_key?(key)
+      delegates.has_key?(key) || store.has_key?(key) 
     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
+    
+    # Merges another with self.
+    def merge!(another)
+      if bound?
+        (delegates.keys | another.keys).each do |key|
+          self[key] = another[key] if another.has_key?(key)
+        end
+      else
+        # optimization for the common case of an 
+        # unbound merge of another hash
+        store.merge!(another.to_hash)
       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
+    # Calls block once for each key-value pair stored in self.
+    def each_pair # :yields: key, value
+      keys.each {|key| yield(key, self[key]) }
     end
 
     # Equal if the to_hash values of self and another are equal.
@@ -148,12 +152,13 @@ module Configurable
       another.respond_to?(:to_hash) && to_hash == another.to_hash
     end
 
-    # Returns self as a hash. 
+    # Returns self as a hash.  Any DelegateHash values are recursively
+    # hashified, to account for nesting.
     def to_hash
-      hash = store.dup
-      delegates.keys.each do |key|
-        hash[key] = self[key]
-      end if bound?
+      hash = {}
+      each_pair do |key, value|
+        hash[key] = value.kind_of?(DelegateHash) ? value.to_hash : value
+      end
       hash
     end
 
@@ -161,5 +166,43 @@ module Configurable
     def inspect
       "#<#{self.class}:#{object_id} to_hash=#{to_hash.inspect}>"
     end
+    
+    # Ensures duplicates are unbound and store the same values as the original.
+    def initialize_copy(orig)
+      super
+      
+      @receiver = nil
+      @store = @store.dup
+      orig.unmap(@store) if orig.bound?
+    end
+    
+    protected
+    
+    # helper to map delegate values from source to the receiver
+    def map(source) # :nodoc:
+      delegates.each_pair do |key, delegate|
+        next unless writer = delegate.writer
+        
+        # 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[:map_default, true] then delegate.default
+        else next
+        end
+        
+        receiver.send(writer, value)
+      end
+    end
+    
+    # helper to unmap delegates from the receiver to a target hash
+    def unmap(target) # :nodoc:
+      delegates.each_pair do |key, delegate|
+        next unless reader = delegate.reader
+        target[key] = receiver.send(reader)
+      end
+    end
   end
 end

data/lib/configurable/indifferent_access.rb

@@ -1,21 +1,34 @@
 module Configurable
+  
+  # Implements AGET and ASET methods that symbolize string keys, in effect 
+  # producing indifferent access.  IndifferentAccess is intended to extend
+  # a Hash.
+  #
+  # 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.
   module IndifferentAccess
-
+    
+    # Symbolizes string keys and calls super.
     def [](key)
       super(convert(key))
     end
-  
+    
+    # Symbolizes string keys and calls super.
     def []=(key, value)
       super(convert(key), value)
     end
-  
-    def key?(key)
-      super(convert(key))
+    
+    # Ensures duplicates use indifferent access.
+    def dup
+      super().extend IndifferentAccess
     end
-  
+    
     private
-  
-    def convert(key)
+    
+    # a helper to convert strings to symbols
+    def convert(key) # :nodoc:
       key.kind_of?(String) ? key.to_sym : key
     end
   end

data/lib/configurable/utils.rb

@@ -0,0 +1,193 @@
+module Configurable
+  
+  # Utility methods to dump and load configurations, particularly nested
+  # configurations.
+  module Utils
+    module_function
+    
+    default_dump_block = lambda do |key, delegate|
+      default = delegate.default(false)
+      
+      # note: this causes order to be lost...
+      default = default.to_hash if delegate.is_nest?
+      YAML.dump({key => default})[5..-1]
+    end
+    
+    # A block performing the default YAML dump.
+    DEFAULT_DUMP = default_dump_block
+    
+    default_load_block = lambda do |base, key, value|
+      base[key] ||= value
+    end
+    
+    # A block performing the default load.
+    DEFAULT_LOAD = default_load_block
+    
+    # Dumps delegates to target as yaml.  Delegates are output in order, and
+    # symbol keys are be stringified if delegates has been extended with
+    # IndifferentAccess (this produces a nicer config file).
+    #
+    #   class DumpExample
+    #     include Configurable
+    #
+    #     config :sym, :value      # a symbol config
+    #     config 'str', 'value'    # a string config
+    #   end
+    #
+    #   Utils.dump(DumpExample.configurations, "\n")
+    #   # => %q{
+    #   # sym: :value
+    #   # str: value
+    #   # }
+    #
+    # Dump may be provided with a block to format each (key, delegate) pair;
+    # the block results are pushed directly to target, so newlines must be
+    # specified manually.
+    # 
+    #   Utils.dump(DumpExample.configurations, "\n") do |key, delegate|
+    #     yaml = YAML.dump({key => delegate.default})[5..-1]
+    #     "# #{delegate[:desc]}\n#{yaml}\n"
+    #   end
+    #   # => %q{
+    #   # # a symbol config
+    #   # sym: :value
+    #   #
+    #   # # a string config
+    #   # str: value
+    #   #
+    #   # }
+    #
+    def dump(delegates, target="")
+      return dump(delegates, target, &DEFAULT_DUMP) unless block_given?
+      
+      stringify = delegates.kind_of?(IndifferentAccess)
+      delegates.each_pair do |key, delegate|
+        key = key.to_s if stringify && key.kind_of?(Symbol)
+        target << yield(key, delegate)
+      end
+      
+      target
+    end
+    
+    # Dumps the delegates to the specified file.  If recurse is true, nested
+    # configurations are each dumped to their own file, based on the nesting
+    # key.  For instance if you nested a in b:
+    #
+    #   a_configs = {
+    #     'key' => Delegate.new(:r, :w, 'a default')}
+    #   b_configs = {
+    #     'key' => Delegate.new(:r, :w, 'b default')}
+    #     'a' => Delegate.new(:r, :w, DelegateHash.new(a_configs))}}
+    #
+    #   Utils.dump_file(b_configs, 'b.yml')
+    #   File.read('b.yml')         # => "key: b default"
+    #   File.read('b/a.yml')       # => "key: a default"
+    #
+    # In this way, each nested config gets it's own file.  The load_file method
+    # can recursively load configurations from this file structure. When recurse
+    # is false, all configs are dumped to a single file.
+    #
+    # dump_file uses a method that collects all dumps in a preview array before
+    # dumping, so that the dump results can be redirected other places than the
+    # file system.  If preview is set to false, no files will be created.  The
+    # preview dumps are always returned by dump_file.
+    #
+    # ==== Note
+    # For load_file to correctly load a recursive dump, all delegate hashes
+    # must use String keys.  Symbol keys are allowed if the delegate hashes use
+    # IndifferentAccess; all other keys will not load properly.  By default 
+    # Configurable is set up to satisfy these conditions.
+    #
+    # 1.8 Bug: Currently dump_file with recurse=false will cause order to be
+    # lost in nested configs. See http://bahuvrihi.lighthouseapp.com/projects/21202-configurable/tickets/8
+    def dump_file(delegates, path, recurse=false, preview=false, &block)
+      return dump_file(delegates, path, recurse, preview, &DEFAULT_DUMP) unless block_given?
+      
+      current = ""
+      dumps = [[path, current]]
+      
+      dump(delegates, current) do |key, delegate|
+        if recurse && delegate.is_nest?
+          nested_delegates = delegate.default(false).delegates
+          nested_dumps = dump_file(nested_delegates, recursive_path(key, path), true, true, &block)
+          
+          dumps.concat(nested_dumps)
+          ""
+        else
+          yield(key, delegate)
+        end
+      end
+      
+      dumps.each do |dump_path, content|
+        dir = File.dirname(dump_path)
+        Dir.mkdir(dir) unless File.exists?(dir)
+        File.open(dump_path, "w") do |io|
+          io << content
+        end 
+      end unless preview
+      
+      dumps
+    end
+    
+    # Loads the string as YAML.
+    def load(str)
+      YAML.load(str)
+    end
+    
+    # Loads the file contents as YAML.  If recurse is true, a hash will be
+    # recursively loaded.  A block may be provided to set recursively loaded
+    # values in the hash loaded from the path.
+    def load_file(path, recurse=false, &block)
+      return load_file(path, recurse, &DEFAULT_LOAD) if recurse && !block_given?
+      base = File.file?(path) ? (YAML.load_file(path) || {}) : {}
+      
+      if recurse
+        # determine the files/dirs to load recursively
+        # and add them to paths by key (ie the base
+        # name of the path, minus any extname)
+        paths = {}
+        files, dirs = Dir.glob("#{path.chomp(File.extname(path))}/*").partition do |sub_path|
+          File.file?(sub_path)
+        end
+
+        # directories are added to paths first so they can be
+        # overridden by the files (appropriate since the file
+        # will recursively load the directory if it exists)
+        dirs.each do |dir|
+          paths[File.basename(dir)] = dir
+        end
+
+        # when adding files, check that no two files map to
+        # the same key (ex a.yml, a.yaml).
+        files.each do |filepath|
+          key = File.basename(filepath).chomp(File.extname(filepath))
+          if existing = paths[key]
+            if File.file?(existing)
+              confict = [File.basename(paths[key]), File.basename(filepath)].sort
+              raise "multiple files load the same key: #{confict.inspect}"
+            end
+          end
+
+          paths[key] = filepath
+        end
+
+        # recursively load each file and reverse merge
+        # the result into the base
+        paths.each_pair do |key, recursive_path|
+          value = load_file(recursive_path, true, &block)
+          yield(base, key, value)
+        end
+      end
+
+      base
+    end
+    
+    # A helper to create and prepare a recursive dump path.
+    def recursive_path(key, path)
+      ext = File.extname(path)
+      dir = path.chomp(ext)
+      
+      "#{File.join(dir, key.to_s)}#{ext}"
+    end
+  end
+end