cascading-configuration-hash 1.0.0

data/README.rdoc

@@ -0,0 +1,138 @@
+== Cascading Configuration
+
+http://rubygems.org/gems/cascading-configuration-hash
+
+== DESCRIPTION:
+
+Adds methods for cascading configuration hashes. Support package for cascading-configuration.
+
+== SUMMARY:
+  
+  * :attr_configuration_hash
+
+== INSTALL:
+
+  * sudo gem install cascading-configuration-hash
+
+== EXAMPLE:
+
+  #############################################################################
+  ######################### attr_configuration_hash ###########################
+  #############################################################################
+
+  ##################
+  #  first module  #
+  ##################
+
+  module CascadingConfiguration::MockModule
+    attr_configuration_hash :some_hash_configuration
+    self.some_hash_configuration = { :some_value => :some_value }
+    # => some_hash_configuration.should == { :some_value => :some_value }
+  end
+
+  ########################
+  #  including module 1  #
+  ########################
+
+  module CascadingConfiguration::MockModule2
+    # => some_hash_configuration.should == { :some_value => :some_value }
+    self.some_hash_configuration = { :module_value => :some_value }
+    # => some_hash_configuration.should == { :module_value => :some_value }
+  end
+
+  ########################
+  #  including module 2  #
+  ########################
+
+  module CascadingConfiguration::MockModule3
+
+  end
+
+  ###############
+  #  top class  #
+  ###############
+
+  class CascadingConfiguration::MockClass
+    # => some_hash_configuration.should == { :module_value => :some_value }
+    self.some_hash_configuration = { :another_value => :some_value }
+    # => some_hash_configuration.should == { :another_value => :some_value }
+  end
+
+  ###########################
+  #  instance of top class  #
+  ###########################
+
+  object_instance_one = CascadingConfiguration::MockClass.new
+  # => object_instance_one.some_hash_configuration.should == { :another_value => :some_value }
+  object_instance_one.some_hash_configuration = { :yet_another_value => :some_value }
+  # => object_instance_one.some_hash_configuration.should == { :yet_another_value => :some_value }
+  # => CascadingConfiguration::MockClass.some_hash_configuration.should == { :another_value => :some_value }
+  # => CascadingConfiguration::MockModule.some_hash_configuration.should == { :some_value => :some_value }
+
+  ############################
+  #  first inheriting class  #
+  ############################
+
+  class CascadingConfiguration::MockClassSub1 < CascadingConfiguration::MockClass
+    # => some_hash_configuration.should == { :another_value => :some_value }
+    self.some_hash_configuration = { :a_value_not_yet_used => :some_value }
+    # => some_hash_configuration.should == { :a_value_not_yet_used => :some_value }
+    # => CascadingConfiguration::MockClass.some_hash_configuration.should == { :another_value => :some_value }
+    # => CascadingConfiguration::MockModule.some_hash_configuration.should == { :some_value => :some_value }
+  end
+
+  ########################################
+  #  instance of first inheriting class  #
+  ########################################
+
+  object_instance_two = CascadingConfiguration::MockClassSub1.new
+  # => object_instance_two.some_hash_configuration.should == { :a_value_not_yet_used => :some_value }
+  # => object_instance_one.some_hash_configuration.should == { :yet_another_value => :some_value }
+  # => CascadingConfiguration::MockClass.some_hash_configuration.should == { :another_value => :some_value }
+  # => CascadingConfiguration::MockModule.some_hash_configuration.should == { :some_value => :some_value }
+
+  #############################
+  #  second inheriting class  #
+  #############################
+
+  class CascadingConfiguration::MockClassSub2 < CascadingConfiguration::MockClassSub1
+    # => some_hash_configuration.should == { :a_value_not_yet_used => :some_value }
+    self.some_hash_configuration = { :another_value_not_yet_used => :some_value }
+    # => some_hash_configuration.should == { :another_value_not_yet_used => :some_value }
+  end
+
+  #########################################
+  #  instance of second inheriting class  #
+  #########################################
+
+  object_instance_three = CascadingConfiguration::MockClassSub2.new
+  # => object_instance_three.some_hash_configuration.should == { :another_value_not_yet_used => :some_value }
+  object_instance_three.some_hash_configuration = { :one_more_unused_value => :some_value }
+  # => object_instance_three.some_hash_configuration.should == { :one_more_unused_value => :some_value }
+
+  #############################################################################
+
+== LICENSE:
+
+  (The MIT License)
+
+  Copyright (c) 2011 Asher
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  'Software'), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be
+  included in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/cascading-configuration-hash/CascadingConfiguration/CascadingCompositeHash/Instance.rb

@@ -0,0 +1,35 @@
+
+module CascadingConfiguration::CascadingCompositeHash::Instance
+
+  ###################
+  #  self.included  #
+  ###################
+
+  def self.included( class_or_module )
+    module_self = self
+    class_or_module.instance_eval do
+      extend module_self
+    end
+  end
+
+  ################################################
+  #  composite_hash_for_cascading_configuration  #
+  ################################################
+
+  def composite_hash_for_cascading_configuration( configuration_name )
+    
+    # initialize composite hash if necessary or acquire it from object
+    composite_hash_variable = composite_hash_variable_name( configuration_name )
+    composite_hash = nil
+    if instance_variable_defined?( composite_hash_variable )
+      composite_hash = instance_variable_get( composite_hash_variable )
+    else
+      composite_hash = ::CascadingConfiguration::CascadingCompositeHash.new( configuration_name, self )
+      instance_variable_set( composite_hash_variable, composite_hash )
+    end
+    
+    return composite_hash
+    
+  end
+
+end

data/lib/cascading-configuration-hash/CascadingConfiguration/CascadingCompositeHash/_private_/Instance.rb

@@ -0,0 +1,16 @@
+
+module CascadingConfiguration::CascadingCompositeHash::Instance
+
+  ###########################################################################################################
+      private ###############################################################################################
+  ###########################################################################################################
+
+  ##################################
+  #  composite_hash_variable_name  #
+  ##################################
+  
+  def composite_hash_variable_name( configuration_name )
+    return ( cascading_variable_name( configuration_name ).to_s + '__' + 'composite_hash' ).to_sym
+  end
+
+end

data/lib/cascading-configuration-hash/CascadingConfiguration/CascadingCompositeHash.rb

@@ -0,0 +1,133 @@
+
+class CascadingConfiguration::CascadingCompositeHash < Hash
+
+  attr_accessor  :working_instance, :local_cascading_hash
+
+  ################
+  #  initialize  #
+  ################
+  
+  def initialize( cascading_name, working_instance )
+    @cascading_name     = cascading_name
+    @cascading_variable = working_instance.cascading_variable_name( @cascading_name )
+    @working_instance   = working_instance
+    # if first ancestor can have a composite array, register self with it in case it gets updated in the future
+    if ( first_ancestor = @working_instance.first_ancestor ).respond_to?( :composite_hash_for_cascading_configuration )
+      @parent_composite_hash = first_ancestor.composite_hash_for_cascading_configuration( @cascading_name )
+      @parent_composite_hash.register_child_composite_hash( self )
+    end
+    # get local cascading array (not included in parent composite)
+    @local_cascading_hash = ::CascadingConfiguration::ConfigurationHash.new
+    # we may later have our own child composites
+    @child_composite_hashes = Array.new
+    # initialize self status for parent and local
+    update_self_as_cascading_composite
+  end
+
+  ###################################
+  #  register_child_composite_hash  #
+  ###################################
+
+  def register_child_composite_hash( child_composite_hash )
+    @child_composite_hashes.push( child_composite_hash )
+    return self
+  end
+
+  #####################################
+  #  unregister_child_composite_hash  #
+  #####################################
+
+  def unregister_child_composite_hash( child_composite_hash )
+    @child_composite_hashes.delete( child_composite_hash )
+    return self
+  end
+
+  #########
+  #  []=  #
+  #########
+
+  def []=( key, value )
+    @local_cascading_hash[ key ] = value
+    update_adding_composite_elements( key => value )
+  end
+  alias_method :store, :[]=
+
+  ############
+  #  delete  #
+  ############
+
+  alias_method :super_delete, :delete
+  def delete( key )
+    value = self[ key ]
+    @local_cascading_hash.delete( key )
+    update_removing_composite_elements( key )
+    return value
+  end
+
+  ############
+  #  merge!  #
+  ############
+  
+  alias_method :super_merge!, :merge!
+  def merge!( other_hash )
+    @local_cascading_hash.merge!( other_hash )
+    update_adding_composite_elements( other_hash )
+    return self
+  end
+  
+  #############
+  #  replace  #
+  #############
+  
+  def replace( other_hash )
+    # clear current values
+    clear
+    # merge replacement settings
+    merge!( other_hash )
+    return self
+  end
+
+  ###########
+  #  shift  #
+  ###########
+  
+  def shift
+    element = super
+    key = element[ 0 ]
+    @local_cascading_hash.delete( key )
+    update_removing_composite_elements( key )
+    return element
+  end
+
+  ###########
+  #  clear  #
+  ###########
+  
+  alias_method :super_clear, :clear
+  def clear
+    # add all existing values to exclude array
+    self.keys.each do |this_key|
+      delete( this_key )
+    end
+    update_removing_composite_elements( *self.keys )
+    return self
+  end
+  
+  #############
+  #  freeze!  #
+  #############
+
+  # freezes configuration and prevents ancestors from changing this configuration in the future
+  def freeze!
+    
+    # move current configuration into local configuration
+    @local_cascading_hash.replace( self )
+    
+    # unregister with parent composite so we don't get future updates from it
+    @parent_composite_hash.unregister_child_composite_hash( self ) if @parent_composite_hash
+    
+    return self
+    
+  end
+  
+end

data/lib/cascading-configuration-hash/CascadingConfiguration/ConfigurationHash.rb

@@ -0,0 +1,83 @@
+
+class CascadingConfiguration::ConfigurationHash < Hash
+  
+  attr_accessor  :exclude_array
+  
+  ################
+  #  initialize  #
+  ################
+
+  def initialize()
+    @exclude_array = Array.new
+  end
+  
+  #########
+  #  []=  #
+  #########
+
+  def []=( key, value )
+    super
+    remove_from_exclude_array( key )
+  end
+
+  ###########
+  #  store  #
+  ###########
+
+  def store( key, value )
+    self[ key ] = value
+  end
+
+  ############
+  #  delete  #
+  ############
+
+  def delete( key )
+    value = super
+    add_to_exclude_array( key )
+    return value
+  end
+
+  ############
+  #  merge!  #
+  ############
+  
+  def merge!( other_hash )
+    super
+    remove_from_exclude_array( *other_hash.keys )
+    return self
+  end
+  
+  #############
+  #  replace  #
+  #############
+  
+  def replace( other_hash )
+    add_to_exclude_array( *self.keys )
+    super
+  end
+
+  ###########
+  #  shift  #
+  ###########
+  
+  def shift
+    element = super
+    add_to_exclude_array( element )
+    return element
+  end
+
+  ###########
+  #  clear  #
+  ###########
+  
+  def clear
+    # add all existing values to exclude array
+    self.each do |this_key, this_value|
+      delete( this_key )
+    end
+    # clear existing values
+    super
+  end
+
+end

data/lib/cascading-configuration-hash/CascadingConfiguration/ConfigurationSettingsHash/Accessors.rb

@@ -0,0 +1,35 @@
+
+module CascadingConfiguration::ConfigurationSettingsHash::Accessors
+
+  ######################################
+  #  define_configuration_hash_setter  #
+  ######################################
+  
+  def define_configuration_hash_setter( configuration_name )
+    [ self, eigenclass ].each do |klass_or_eigenclass|
+      klass_or_eigenclass.class_eval do
+        configuration_setter_name = ( configuration_name.to_s + '=' ).to_sym
+        define_method( configuration_setter_name ) do |hash|
+          # we want the hash to supplant existing config
+          return composite_hash_for_cascading_configuration( configuration_name ).replace( hash )
+        end
+      end
+    end
+  end
+
+  ######################################
+  #  define_configuration_hash_getter  #
+  ######################################
+  
+  def define_configuration_hash_getter( configuration_name )
+    configuration_getter_name = configuration_name
+    [ self, eigenclass ].each do |klass_or_eigenclass|
+      klass_or_eigenclass.class_eval do
+        define_method( configuration_getter_name ) do
+          return composite_hash_for_cascading_configuration( configuration_name )
+        end
+      end
+    end
+  end
+
+end

data/lib/cascading-configuration-hash/CascadingConfiguration/ConfigurationSettingsHash/ClassInstance.rb

@@ -0,0 +1,21 @@
+
+module CascadingConfiguration::ConfigurationSettingsHash::ClassInstance
+
+  #############################
+  #  attr_configuration_hash  #
+  #############################
+
+  def attr_configuration_hash( *property_names )
+    
+    property_names.each do |this_property_name|
+      # define configuration setter
+      define_configuration_hash_setter( this_property_name )
+      # define configuration getter
+      define_configuration_hash_getter( this_property_name )
+    end
+    
+    return self
+
+  end
+
+end

data/lib/cascading-configuration-hash/CascadingConfiguration/ConfigurationSettingsHash/ModuleInstance.rb

@@ -0,0 +1,20 @@
+
+module CascadingConfiguration::ConfigurationSettingsHash::ModuleInstance
+  
+  ##############
+  #  included  #
+  ##############
+  
+  def included( class_or_module )
+    self_module = self
+    class_or_module.instance_eval do
+      include CascadingConfiguration::ConfigurationSettingsHash
+      # when we extend a module (which has happened if we got here)
+      # then we need to make sure when the module we are extending is included
+      # * CascadingConfiguration is included
+      # * the module we extended is used to extend the class/module that included
+      extend  self_module
+    end
+  end
+  
+end

data/lib/cascading-configuration-hash/CascadingConfiguration/ConfigurationSettingsHash.rb

@@ -0,0 +1,21 @@
+
+module CascadingConfiguration::ConfigurationSettingsHash
+  
+  ###################
+  #  self.included  #
+  ###################
+
+  def self.included( class_or_module )
+    class_or_module.instance_eval do
+      include CascadingConfiguration::ConfigurationVariable
+      extend  CascadingConfiguration::ConfigurationSettingsHash
+      extend  CascadingConfiguration::ConfigurationSettingsHash::Accessors
+      extend  CascadingConfiguration::ConfigurationSettingsHash::ClassInstance
+      include CascadingConfiguration::CascadingCompositeHash::Instance
+      unless class_or_module.is_a?( Class )
+        extend CascadingConfiguration::ConfigurationSettingsHash::ModuleInstance
+      end
+    end
+  end
+
+end

data/lib/cascading-configuration-hash/CascadingConfiguration/_private_/CascadingCompositeHash.rb

@@ -0,0 +1,60 @@
+
+class CascadingConfiguration::CascadingCompositeHash < Hash
+  
+  ###########################################################################################################
+      private ###############################################################################################
+  ###########################################################################################################
+
+  ########################################
+  #  update_self_as_cascading_composite  #
+  ########################################
+
+  def update_self_as_cascading_composite
+    # start fresh
+    super_clear
+    # add parent config
+    super_merge!( @parent_composite_hash ) if @parent_composite_hash
+    # add additional local config
+    super_merge!( @local_cascading_hash )
+    # remove local exclude
+    unless @local_cascading_hash.exclude_array.empty?
+      @local_cascading_hash.exclude_array.each do |this_excluded_element|
+        super_delete( this_excluded_element )
+      end
+    end
+    # notify children to update their composite status
+    update_child_composite_arrays
+    return self
+  end
+  
+  ######################################
+  #  update_adding_composite_elements  #
+  ######################################
+
+  def update_adding_composite_elements( elements_to_cascade )
+    super_merge!( elements_to_cascade )
+    update_child_composite_arrays
+  end
+
+  ########################################
+  #  update_removing_composite_elements  #
+  ########################################
+
+  def update_removing_composite_elements( *elements_to_exclude )
+    elements_to_exclude.each do |this_key|
+      super_delete( this_key )
+    end
+    update_child_composite_arrays
+  end
+
+  ###################################
+  #  update_child_composite_arrays  #
+  ###################################
+  
+  def update_child_composite_arrays
+    @child_composite_hashes.each do |this_composite_hash|
+      this_composite_hash.instance_eval { update_self_as_cascading_composite }
+    end
+  end
+    
+end

data/lib/cascading-configuration-hash/CascadingConfiguration/_private_/ConfigurationHash.rb

@@ -0,0 +1,31 @@
+
+class CascadingConfiguration::ConfigurationHash < Hash
+
+  ###########################################################################################################
+      private ###############################################################################################
+  ###########################################################################################################
+
+  ##########################
+  #  add_to_exclude_array  #
+  ##########################
+
+  def add_to_exclude_array( *elements )
+    @exclude_array ||= Array.new
+    @exclude_array += elements
+    @exclude_array.sort!.uniq!
+  end
+
+  ###############################
+  #  remove_from_exclude_array  #
+  ###############################
+
+  def remove_from_exclude_array( *elements )
+    if @exclude_array
+      @exclude_array -= elements
+      @exclude_array.sort!.uniq!
+    else
+      @exclude_array ||= Array.new
+    end
+  end
+  
+end

data/lib/cascading-configuration-hash.rb

@@ -0,0 +1,33 @@
+
+require 'cascading-configuration-variable'
+#require_relative '../../variable/lib/cascading-configuration-variable.rb'
+
+module CascadingConfiguration
+  class CascadingCompositeHash < Hash
+    module Instance
+    end
+  end
+  class ConfigurationHash < Hash
+  end
+  module ConfigurationSettingsHash
+    module Accessors
+    end
+    module ClassInstance
+    end
+    module ObjectInstance
+    end
+    module ModuleInstance
+    end
+  end
+end
+
+require_relative 'cascading-configuration-hash/CascadingConfiguration/CascadingCompositeHash.rb'
+require_relative 'cascading-configuration-hash/CascadingConfiguration/_private_/CascadingCompositeHash.rb'
+require_relative 'cascading-configuration-hash/CascadingConfiguration/CascadingCompositeHash/Instance.rb'
+require_relative 'cascading-configuration-hash/CascadingConfiguration/CascadingCompositeHash/_private_/Instance.rb'
+require_relative 'cascading-configuration-hash/CascadingConfiguration/ConfigurationHash.rb'
+require_relative 'cascading-configuration-hash/CascadingConfiguration/_private_/ConfigurationHash.rb'
+require_relative 'cascading-configuration-hash/CascadingConfiguration/ConfigurationSettingsHash.rb'
+require_relative 'cascading-configuration-hash/CascadingConfiguration/ConfigurationSettingsHash/Accessors.rb'
+require_relative 'cascading-configuration-hash/CascadingConfiguration/ConfigurationSettingsHash/ClassInstance.rb'
+require_relative 'cascading-configuration-hash/CascadingConfiguration/ConfigurationSettingsHash/ModuleInstance.rb'